Docs
Get started

SDKs

Go SDK

Official Go SDK for LiveXFace. Requires Go 1.22 or later.

Installation

Shell
go get github.com/livexface/livexface-go

Quick Start

Go
package main

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

    "github.com/livexface/livexface-go"
)

func main() {
    client := livexface.New(os.Getenv("LIVEXFACE_API_KEY"))
    ctx := context.Background()
    collectionID := os.Getenv("LIVEXFACE_COLLECTION_ID")

    // Register a face
    imageBytes, _ := os.ReadFile("alice.jpg")
    face, err := client.Faces.Register(ctx, collectionID, livexface.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, collectionID, livexface.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

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

Face Operations

All face operations are on the client.Faces resource:

Register a face

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

1:1 Verification

Go
result, err := client.Faces.Verify(ctx, collectionID, livexface.VerifyInput{
    FaceID: "dc3e7a57-22d5-4271-b707-213e49c8fe54",
    Image:  probeBytes,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("match:", result.Match, "confidence:", result.Confidence)

1:N Identification

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

Liveness Detection

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

Batch Register

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

Collections

Collections are created and managed in the dashboard, not through the API, so the client has no collection operations. Create one there and pass its ID to the calls above.

Error Handling

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

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

Method Reference

Faces

MethodDescription
Faces.Register(ctx, collID, RegisterInput)Enroll a face
Faces.List(ctx, collID, ListOptions)Paginated face list
Faces.Get(ctx, collID, faceID)Get a face by ID
Faces.Delete(ctx, collID, faceID)Remove a face
Faces.Verify(ctx, collID, VerifyInput)1:1 verification
Faces.Identify(ctx, collID, IdentifyInput)1:N search
Faces.Liveness(ctx, collID, image, filename)Liveness detection
Faces.Compare(ctx, CompareInput)Compare two images
Faces.BatchRegister(ctx, collID, []BatchItem)Bulk enroll up to 20 faces, synchronously
Faces.BatchRegisterAsync(ctx, collID, []BatchItem)Queue the same enrollment and get a job back
Faces.GetBatchJob(ctx, collID, jobID)Poll an async batch job
Faces.Attributes(ctx, collID, image, filename)Age, gender, pose, emotion, glasses, mask

Collections

MethodDescription
Collections.List(ctx)List all collections
Collections.Get(ctx, collID)Get a collection
Collections.Create(ctx, CreateCollectionInput)Create a collection
Collections.Update(ctx, collID, UpdateCollectionInput)Update a collection
Collections.Delete(ctx, collID)Delete a collection