Official Go SDK for FR-APIaaS. Requires Go 1.22 or later.

Installation

go get github.com/fr-apiaas/fr-apiaas-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    frapiaas "github.com/fr-apiaas/fr-apiaas-go"
)

func main() {
    client := frapiaas.New(os.Getenv("FR_API_KEY"))
    ctx := context.Background()

    // Register a face
    imageBytes, _ := os.ReadFile("alice.jpg")
    face, err := client.Faces.Register(ctx, "col_01abc...", frapiaas.RegisterInput{
        ExternalID: "user_alice",
        Image:      imageBytes,
        Metadata:   map[string]interface{}{"name": "Alice Smith"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Registered face:", face.ID)

    // Identify a face
    probeBytes, _ := os.ReadFile("probe.jpg")
    result, err := client.Faces.Identify(ctx, "col_01abc...", frapiaas.IdentifyInput{
        Image: probeBytes,
        TopK:  3,
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, match := range result.Matches {
        fmt.Printf("Match: %s  confidence=%.3f\n", match.ExternalID, match.Confidence)
    }
}

Configuration

client := frapiaas.New(
    "fr_live_xxxx",
    frapiaas.WithBaseURL("https://your-instance.example.com/api/v1"),
    frapiaas.WithTimeout(15 * time.Second),
)

Face Operations

All face operations are on the client.Faces resource:

Register a face

face, err := client.Faces.Register(ctx, collectionID, frapiaas.RegisterInput{
    ExternalID: "user_123",
    Image:      imageBytes,
    Metadata:   map[string]interface{}{"department": "engineering"},
})

1:1 Verification

result, err := client.Faces.Verify(ctx, collectionID, frapiaas.VerifyInput{
    FaceID: "face_01abc...",
    Image:  probeBytes,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("match:", result.Match, "confidence:", result.Confidence)

1:N Identification

result, err := client.Faces.Identify(ctx, collectionID, frapiaas.IdentifyInput{
    Image: probeBytes,
    TopK:  5,
})
for _, m := range result.Matches {
    fmt.Printf("%s — %.3f\n", m.ExternalID, m.Confidence)
}

Liveness Detection

result, err := client.Faces.Liveness(ctx, collectionID, imageBytes, "selfie.jpg")
fmt.Println("live:", result.Live, "score:", result.Score)

Batch Register

items := []frapiaas.BatchItem{
    {ExternalID: "user_a", Image: imgA},
    {ExternalID: "user_b", Image: imgB},
}
resp, err := client.Faces.BatchRegister(ctx, collectionID, items)

Collection Operations

// List all collections
collections, err := client.Collections.List(ctx)

// Create a collection
col, err := client.Collections.Create(ctx, frapiaas.CreateCollectionInput{
    Name:        "employees",
    Description: "Active employee faces",
})

// Delete a collection
err = client.Collections.Delete(ctx, collectionID)

Error Handling

All methods return a standard error. Use errors.As to check for API-level errors:

result, err := client.Faces.Identify(ctx, collID, input)
if err != nil {
    var apiErr *frapiaas.APIError
    if errors.As(err, &apiErr) {
        fmt.Println("code:", apiErr.Code)
        fmt.Println("status:", apiErr.StatusCode)
        fmt.Println("request_id:", apiErr.RequestID)
    }
}

Method Reference

Faces

Collections