Todos los productos
Search
Centro de documentos

ID Verification:FACE_IDU_MIN

Última actualización: Sep 09, 2026

FACE_IDU_MIN es un servicio de detección de vida basado en API. Utiliza el modelo grande Qwen-VL para analizar una imagen facial capturada previamente y detectar riesgos de ataques de suplantación, con el fin de determinar si el rostro pertenece a una persona real. El servicio también admite opciones de verificación flexibles, como la verificación 1:1 contra una imagen facial almacenada y la búsqueda 1:N dentro de un grupo de rostros para comprobar duplicados. Además, cuando la verificación se completa correctamente, registra automáticamente el rostro en el grupo de rostros especificado.

Referencia de la API

  • Operación: FaceVerifyIntl

  • Método de solicitud: POST sobre HTTPS

  • Descripción: llame a la operación FaceVerifyIntl para ejecutar la verificación de vida.

  • Límite de QPS: esta operación tiene un límite de QPS dedicado. Para obtener más información, consulte QPS limits of ID Verification server-side APIs.

  • Endpoints:

    Nota
    • Ventajas del acceso por red interna: 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 está desplegado en la misma región, utilice el endpoint interno para acceder al servicio ID Verification. Esto mejora la seguridad y la estabilidad.

    • Optimización del acceso desde el extranjero: los entornos de red internacionales suelen ser complejos. Consulte Optimize server network latency para ajustar su integración, reducir la latencia de red y disminuir las solicitudes con errores.

    Singapore

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

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

    Indonesia (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

    Malaysia (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 la API, asegúrese de haber leído la documentación de Use OpenAPI para comprender cómo llamar a las API y obtener los SDK en la plataforma OpenAPI.

Ejecute esta operación en OpenAPI Explorer para depurarla y generar ejemplos de código del SDK.

Parámetros de solicitud

Parámetros de la imagen facial

  • Proporcione la imagen facial mediante uno de los tres métodos siguientes:

    • Modo Base64: SourceFacePicture/TargetFacePicture

    • Modo URL: SourceFacePictureUrl/TargetFacePictureUrl

    • Modo flujo de archivo: SourceFacePictureFile/TargetFacePictureFile

  • Formato de imagen: JPG, JPEG o PNG.

  • Tamaño de imagen: se recomiendan entre 50 y 100 KB, con un máximo de 1 MB.

  • Resolución de imagen: máximo 1920*1080 (alto × ancho) y mínimo 640*480 (alto × ancho). Escale el lado más corto a 720 px con una relación de compresión > 0.9. La altura debe superar al ancho, ya que la orientación horizontal puede reducir la precisión.

    Nota

    La codificación Base64 aumenta el tamaño del archivo. Mantenga la imagen original por debajo de 0.6 MB para no exceder el límite de transferencia de 1 MB.

  • Recomendaciones de calidad de imagen:

    • El rostro debe estar completo, nítido, sin obstrucciones y de frente. Utilice una cámara frontal.

    • El rostro debe ocupar más del 60 % del área de la imagen. Los rostros pequeños reducen la precisión.

    • Si hay varios rostros, el algoritmo procesa el más grande. Evite imágenes con múltiples rostros.

Detalles de los parámetros de solicitud

Parámetro

Tipo

Obligatorio

Descripción

Ejemplo

ProductCode

String

Sí

Identificador de la solución de producto. Establezca el valor en FACE_IDU_MIN.

FACE_IDU_MIN

MerchantBizId

String

Sí

Identificador de negocio único del comerciante, que se utiliza para identificar y solucionar problemas. Es una cadena de 32 caracteres formada por letras y números. El servidor no valida la unicidad de este identificador, por lo que el comerciante debe asegurarse de que sea único.

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

Sí

Identificador de usuario personalizado, u otro identificador reconocible, como un número de celular o una dirección de correo electrónico. Se recomienda anonimizar o aplicar un hash a este campo.

123456789

SourceFacePicture

String

Sí (elija uno de los tres parámetros SourceFace)

Imagen facial de origen para la detección de vida, codificada en Base64.

base64

SourceFacePictureUrl

String

URL HTTP o HTTPS de acceso público de la imagen facial de origen.

https://***face1.jpeg

SourceFacePictureFile

String

Flujo de archivo de la imagen facial de origen.

Para obtener detalles de integración, consulte Advanced feature for file uploads.

FaceQualityCheck

String

No

[Configuración de detección facial] Indica si se habilita la comprobación de calidad facial, deshabilitada de forma predeterminada. Valores válidos:

  • N: deshabilitado (valor predeterminado).

  • Y: habilitado.

Cuando se habilita, el sistema rechaza automáticamente las imágenes faciales de baja calidad, como las borrosas u ocultas, y evita que se usen en pasos posteriores como la comparación. Se recomienda habilitar esta opción en escenarios que requieren alta precisión o para reducir solicitudes no válidas. Si se rechaza una imagen, la API devuelve un error 401 con el mensaje UnqualifiedPhoto.

N

FaceAttributeCheck

String

No

[Configuración de detección facial] Indica si se devuelve información adicional sobre los atributos faciales.

  • N: deshabilitado (valor predeterminado).

  • Y: habilitado. Si se habilita, los atributos se devuelven como una cadena en el campo faceAttributeInfo dentro del objeto ExtFaceInfo.

N

VerifyModel

String

Sí

[Configuración del producto] Modo de verificación:

  • 1 modo de validación: verificación 1:1 (valor predeterminado)

  • 0 modo de recuperación: recuperación 1:N

  • 2 modo integral: verificación 1:1 + recuperación 1:N

0

TargetFacePicture

String

Obligatorio si VerifyModel es 1 o 2.

[Configuración del producto - validación 1:1] Cadena codificada en Base64 de la imagen facial de destino confiable para la comparación 1:1.

base64

TargetFacePictureUrl

String

[Configuración del producto - validación 1:1] URL de la imagen facial. Debe ser un enlace HTTP o HTTPS de acceso público.

https://***face2.jpeg

TargetFacePictureFile

String

[Configuración del producto - validación 1:1] Flujo de archivo de la imagen facial.

Para obtener detalles de integración, consulte Advanced feature for file uploads.

FaceGroupCodes

String

Obligatorio si VerifyModel es 0 o 2.

[Configuración del producto - recuperación 1:N] Códigos de los grupos de rostros para la recuperación 1:N. Puede obtener el código cuando crea un grupo de rostros en la consola de ID Verification. Es posible especificar hasta 10 grupos de rostros a la vez. Separe varios códigos de grupos de rostros con comas (,).

sgxta,suk3j

ReturnFaces

String

Obligatorio si VerifyModel es 0 o 2.

[Configuración del producto - recuperación 1:N] Número de rostros coincidentes que se devuelven cuando varios rostros superan el umbral de coincidencia. Valor predeterminado: 1. Máximo: 5.

1

AutoRegistration

String

Obligatorio si VerifyModel es 0 o 2.

[Configuración del producto - recuperación 1:N] Indica si se registra automáticamente el rostro en un grupo de rostros después de una verificación correcta:

  • 0: habilita el registro automático.

  • 1: deshabilita el registro automático (valor predeterminado).

0

FaceRegisterGroupCode

String

Obligatorio si VerifyModel es 0 o 2 y AutoRegistration es 0.

[Configuración del producto - recuperación 1:N] Código del grupo de rostros de destino para el registro automático.

sg*xta

UpdateFaceIfUserExists

String

Obligatorio si VerifyModel es 0 o 2.

[Configuración de la solución de producto - búsqueda 1:N] Si el MerchantUserId ya existe durante el registro automático, sobrescribe el rostro existente con el nuevo:

  • Y: sobrescribe.

  • N: no sobrescribe (valor predeterminado). El servicio devuelve un error "UserId already exists".

N

Tres modos de verificación

Modo de verificación

Valor de VerifyModel

Lógica principal

Caso de uso

Parámetros clave

Condición de registro automático

Modo de validación (valor predeterminado)

1

detección de vida + validación 1:1

Inicios de sesión, recuperación de cuentas y confirmación de acciones sensibles.

TargetFacePicture, TargetFacePictureUrl o TargetFacePictureFile (elija uno de los tres para especificar el rostro de destino)

No aplica

Modo de recuperación

0

detección de vida + recuperación 1:N

Prevención de registros duplicados para usuarios nuevos y aplicación de una cuenta por persona.

FaceGroupCodes (especifica los grupos de rostros donde buscar). ReturnFaces (opcional; indica cuántos rostros devolver que superen el umbral de coincidencia)

La detección de vida se aprueba y la recuperación 1:N no encuentra coincidencias.

Modo integral

2

detección de vida + validación 1:1 + recuperación 1:N

Registro de usuarios nuevos que requiere confirmación de identidad y comprobación de duplicados.

Requiere todos los parámetros clave del modo de validación (valor 1) y del modo de recuperación (valor 0).

La detección de vida se aprueba, la validación 1:1 se aprueba y la recuperación 1:N no encuentra coincidencias.

Response data

Parámetro

Tipo

Descripción

Ejemplo

Código de estado HTTP

Integer

Código de estado HTTP.

200

HTTP Body

RequestId

String

ID de la solicitud.

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

Code

String

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

Success

Message

String

Descripción del código de retorno.

success

Result.TransactionId

String

Identificador único de la solicitud de verificación.

4ab0b***cbde97

Result.SubCode

String

Subcódigo del resultado de verificación. Para obtener más información, consulte Result.SubCode reference.

200

Result.FacePassed

String

Resultado final de la verificación. Valores válidos:

  • Y: aprobado

  • N: rechazado

Y

Result.FaceAttack

String

Indica si se detectó un ataque de suplantación. Valores válidos:

  • Y: sí

  • N: no

N

Result.FaceAttributeInfo

String

Detecta los atributos faciales del rostro principal en una imagen de entrada. El rostro principal es el más grande, nítido y cercano a la cámara. Los resultados de la detección se devuelven como una cadena que permite tomar decisiones sobre el contenido.

Los campos devueltos se definen a continuación:

  • gender: género de la entidad principal. El valor 1 indica hombre y 0 indica mujer.

  • glasses: indica si la entidad principal usa lentes. El valor 1 indica que se detectaron lentes y 0 que no.

  • hat: indica si la entidad principal usa sombrero o gorra, incluidos pañuelos o velos para la cabeza. El valor 1 indica que se detectó y 0 que no.

  • mask: indica si la entidad principal usa cubrebocas. El valor 1 indica que se detectó y 0 que no.

  • tattoo: indica si la entidad principal tiene un tatuaje visible. El valor 1 indica que se detectó y 0 que no.

  • smoking: indica si la entidad principal está fumando. El valor 1 indica que se detectó y 0 que no.

  • others: indica si hay otras personas presentes además de la entidad principal. El valor 1 indica que se detectaron y 0 que no.

  • env: entorno de la entidad principal, como oficina, fábrica, hospital o vehículo. Actualmente, el sistema admite devolver office, hospital, factory, vehicle u other.

  • expression: indica si la entidad principal muestra una expresión exagerada, es decir, una expresión facial intensa distinta de un estado natural o tranquilo. El valor 1 indica que se detectó y 0 que no.

  • age: edad de la entidad principal en años.

{
    "gender": 1,
    "glasses": 0,
    "hat": 1,
    "mask": 1,
    "tattoo": 0,
    "smoking": 0,
    "others": 1,
    "env": "office",
    "expression": 1,
    "age": 16
}

Result.ExtFaceInfo

Object

Información sobre el resultado de la detección de vida. Para conocer el formato JSON, consulte el ejemplo de la derecha. Para obtener más información, consulte Result.ExtFaceInfo.

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

Result.FaceComparisonScore

Double

El resultado de la comparación facial se devuelve cuando VerifyModel=1/2. La puntuación de comparación varía de 0 a 100. El umbral predeterminado del sistema es 90. También es posible personalizar la decisión según sus necesidades de negocio.

98

Result.DuplicateFace

String

Devuelve el resultado de la búsqueda de rostros duplicados cuando VerifyModel es 0 o 2 y se encuentra un rostro similar.

Los campos devueltos se definen a continuación:

  • faceGroupCode: código del grupo de rostros que contiene el rostro similar.

  • faceId: ID del rostro similar.

  • merchantUserId: ID de usuario único del rostro similar.

  • score: puntuación de similitud del rostro.

[
  {
    "faceGroupCode": "sg7****uzt",
    "faceId": "f5a921*******9e792ec84c8f0ca592a",
    "merchantUserId": "face0005",
    "score": 93.26
  }
]

Result.FaceRegistrationResult

Integer

Resultado del registro facial (se devuelve cuando VerifyModel=0/2):

  • 0: el registro falló debido a un problema con la imagen facial.

  • 1: registro correcto.

  • 2: el registro falló porque no se cumplieron las condiciones de registro automático.

  • 3: el registro falló porque el usuario ya existe.

  • 4: registro correcto y actualización exitosa de la imagen facial (esto ocurre cuando una entrada cumple las condiciones de registro automático, pero tiene un MerchantUserId duplicado y UpdateFaceIfUserExists se establece en Y).

1

Result.FaceRegistrationId

String

ID del rostro registrado, que se devuelve cuando VerifyModel=0/2, AutoRegistration=0 y el registro se completa correctamente.

9e792a592a

Result.ExtFaceInfo

Nombre

Tipo

Descripción

Ejemplo

FaceQualityScore

Double

Puntuación de calidad facial para la prueba de vida. Valores válidos: de 0 a 100. Un valor más alto indica mejor calidad.

88.62

OcclusionScore

Double

Subdimensión de evaluación de calidad: puntuación de oclusión. Valores válidos: de 0 a 100. Un valor más alto indica mejor calidad.

99.99

KaOcclusionScore

Double

Subdimensión de evaluación de calidad: puntuación de oclusión en áreas clave. Valores válidos: de 0 a 100. Un valor más alto indica mejor calidad.

100

IlluminationScore

Double

Subdimensión de evaluación de calidad: puntuación de iluminación. Valores válidos: de 0 a 100. Un valor más alto indica mejor calidad.

97.43

SharpnessScore

Double

Subdimensión de evaluación de calidad: puntuación de nitidez de la imagen. Valores válidos: de 0 a 100. Un valor más alto indica mejor calidad.

60.78

Result.Referencia de SubCode

Sub-code

Billable

Description and suggestion

200

Yes

Verification passed.

204

Yes

[Resultado de verificación 1:1] Esto puede deberse a que el usuario no es la misma persona o a que la calidad de la imagen facial es deficiente.

205

Yes

[Resultado de prueba de vida] Se detectó un riesgo de prueba de vida, lo que indica un posible ataque de suplantación.

233

Yes

Resultado de búsqueda 1:N: se detectaron rostros similares. Utilice la información en Result.ExtFaceInfo.duplicateFace para gestionar los riesgos de registro duplicado o suplantación de identidad.