Todos los productos
Search
Centro de documentos

ID Verification:Add a face image to a specified face group

Última actualización: Sep 18, 2026

Esta API agrega una imagen facial a un grupo de rostros específico para su recuperación posterior. También puede crear grupos de rostros y agregar imágenes faciales desde la consola de ID Verification.

Información de la API

  • Nombre de la API: AddFaceRecord

  • Método de solicitud: POST

  • Protocolo de transporte: HTTPS

  • Esta API tiene un límite de 50 QPS por inquilino.

  • Endpoints:

    Nota
    • Una red interna es una red de comunicación privada que conecta los productos de Alibaba Cloud dentro de la misma región. Si su servidor de aplicaciones se despliega en la misma región, utilice el endpoint interno para acceder al servicio ID Verification. Esto mejora la seguridad y la estabilidad.

    • Los distintos planes del producto ID Verification admiten diferentes regiones, y los datos están aislados entre ellas. Debe usar el endpoint correspondiente a la región de sus datos para acceder a ellos.

    Asia Pacific SE 1 (Singapore)

    • Endpoint público: cloudauth-intl.ap-southeast-1.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

    Asia Pacific SE 5 (Jakarta)

    • Endpoint público: cloudauth-intl.ap-southeast-5.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

    China (Hong Kong)

    • Endpoint público: cloudauth-intl.cn-hongkong.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    Asia Pacific SE 3 (Kuala Lumpur)

    • Endpoint público: cloudauth-intl.ap-southeast-3.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

Depuración e integración en línea

Nota

Antes de depurar e integrar, lea el documento Use OpenAPI para aprender cómo invocar las API en la plataforma OpenAPI y obtener el SDK.

Puede ejecutar y depurar esta API en OpenAPI Explorer, y generar un ejemplo de código del SDK.

Requisitos de la imagen

  • Formato de imagen: JPG o JPEG.

  • Tamaño de imagen: se recomienda entre 50 KB y 100 KB. El tamaño máximo es de 10 MB. Para imágenes mayores a 1 MB, se recomienda cargarlas mediante una URL o un flujo de archivo.

  • Resolución de imagen: se recomienda una resolución de 640x480 píxeles (alto x ancho). La resolución máxima es de 1920x1080 píxeles (alto x ancho). El alto de la imagen debe ser mayor que su ancho. Para obtener mejores resultados, escale el lado más corto a 720 píxeles con una relación de compresión de 0.8.

  • Calidad de imagen: la imagen debe ser nítida y tener una exposición adecuada. El rostro no debe verse demasiado oscuro, demasiado brillante ni presentar halos.

  • Varios rostros: si una imagen contiene varios rostros, el sistema detecta y procesa el más grande de forma predeterminada.

Parámetros de solicitud

Nota

Al cargar una imagen facial, proporciónela mediante uno solo de los siguientes parámetros: FacePicture, FacePictureUrl o FacePictureFileObject.

Parámetro

Tipo

Descripción

Obligatorio

Ejemplo

ProductCode

string

El código del producto. Establezca el valor en FACE_ENROLL.

Sí

FACE_ENROLL

FaceGroupCode

string

El código del grupo de rostros.

Sí

sgl****7uc

MerchantUserId

string

Un identificador único personalizado para el usuario, con una longitud máxima de 32 caracteres.

  • Si se proporciona, este identificador se usa para el registro.

  • Si se omite, el sistema genera un identificador predeterminado.

No

130A2C10B9EE4D8488E35384FF03hst

FacePicture

string

La cadena codificada en Base64 de la imagen facial.

No

base64

FacePictureUrl

string

La URL de la imagen facial.

No

https://example.com/test.jpg

FacePictureFileObject

InputStream

El flujo de archivo local de la imagen facial.

Para cargar un archivo con este parámetro, debe invocar la operación Advance API y pasar un objeto InputStream válido. Para más información, consulte Special scenario: Configure the Advance API for file uploads.

No

El objeto InputStream de la imagen

FaceQualityCheck

string

Indica si se comprueba la calidad de la imagen facial.

  • Y: habilita la comprobación de calidad. (Predeterminado)

  • N: deshabilita la comprobación de calidad.

Si se habilita, el sistema rechaza automáticamente las imágenes de baja calidad, como las borrosas u obstruidas, y no las agrega al grupo de rostros. Para las imágenes rechazadas, el sistema devuelve un error 401 (UnqualifiedPhoto).

No

Y

Parámetros de respuesta

Parámetro

Tipo

Descripción

Ejemplo

Código de estado HTTP

integer

El código de estado HTTP.

200

HTTP Body

RequestId

string

El identificador de la solicitud.

130A2C10-B9EE-4D84-88E3-5384FF03****

Code

string

Código de retorno. Para más información, consulte Server-side HTTP status codes.

Success

Message

string

La descripción del código de retorno.

The request was successful.

Result.Passed

string

El resultado del registro.

  • Y: el registro fue exitoso.

  • N: el registro terminó con errores.

Y

Result.ExtFaceInfo

Object

Contiene los resultados del análisis de la imagen facial. Consulte el ejemplo para ver el formato JSON.

Para más información, consulte ExtFaceInfo.

{
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

ExtFaceInfo

Parameter

Type

Description

Ejemplo

FaceQualityScore

Double

La puntuación general de calidad facial. El valor oscila entre 0 y 100. Una puntuación más alta indica mejor calidad.

88.62

OcclusionScore

Double

Subpuntuación de calidad por oclusión. El valor oscila entre 0 y 100. Una puntuación más alta indica mejor calidad (menor oclusión).

99.99

KaOcclusionScore

Double

Subpuntuación de calidad por oclusión en áreas faciales clave. El valor oscila entre 0 y 100. Una puntuación más alta indica mejor calidad.

100

IlluminationScore

Double

Subpuntuación de calidad por iluminación. El valor oscila entre 0 y 100. Una puntuación más alta indica mejor calidad.

97.43

SharpnessScore

Double

Subpuntuación de calidad por nitidez de la imagen. El valor oscila entre 0 y 100. Una puntuación más alta indica mejor calidad.

60.78

Facturación

Esta API genera cargos. Para más información, consulte Billing overview.

Nota

A continuación se muestran las operaciones que no generan cargos:

  • Agregar manualmente una imagen facial en la consola.

  • El registro automático durante un flujo de verificación de vitalidad.