Custom face retrieval

How it works

Custom face retrieval searches a specified person group and returns the top five most similar people, ranked by similarity score in descending order. Each request searches exactly one person group.

For the full list of request and response parameters, see the Custom Face Retrieval API documentation. For available endpoints, see Endpoints.

Prerequisites

Before you begin, ensure that you have:

• Go dependencies installed. For installation steps, see Installation.

Submit a face retrieval task

The following example submits a face retrieval request using the sface-n scene value, which indicates custom face retrieval. Reuse the client instance across requests to improve performance and avoid redundant connections.

package main

import (
    "encoding/json"
    "fmt"
    "os"
    "strconv"

    "github.com/aliyun/alibaba-cloud-sdk-go/services/green"
)

func main() {
    // Initialize the client once and reuse it across requests.
    // Credentials are read from environment variables to avoid hardcoding sensitive values.
    client, err := green.NewClientWithAccessKey(
        "cn-shanghai",
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    )
    if err != nil {
        fmt.Println(err.Error())
        return
    }

    // Build the task. Specify the person group to search in the extras field.
    extras := map[string]interface{}{"groupId": "<person-group-id>"}
    task := map[string]interface{}{
        "dataId": "<data-id>",
        "url":    "<face-image-url>",
        "extras": extras,
    }

    // scenes: the detection scenario. Set the value to sface-n, which indicates custom face retrieval.
    content, _ := json.Marshal(map[string]interface{}{
        "tasks":   task,
        "scenes":  [...]string{"sface-n"},
        "bizType": "<business-scenario>",
    })

    request := green.CreateImageSyncScanRequest()
    request.SetContent(content)

    response, err := client.ImageSyncScan(request)
    if err != nil {
        fmt.Println(err.Error())
        return
    }
    if response.GetHttpStatus() != 200 {
        fmt.Println("response not success. status:" + strconv.Itoa(response.GetHttpStatus()))
        return
    }
    fmt.Println(response.GetHttpContentString())
}

Replace the following placeholders before running the code:

Constraints

• This SDK accepts only public HTTP or HTTPS image URLs. Local files and binary data are not supported.

• The maximum URL length is 2,048 characters.

• Each request searches exactly one person group.

What's next

• Review the full list of request and response parameters in the Custom Face Retrieval API documentation.