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:
NotaVentajas 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.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
Indonesia (Jakarta)
Endpoint público:
cloudauth-intl.ap-southeast-5.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
China (Hong Kong)
Endpoint público:
cloudauth-intl.cn-hongkong.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Malaysia (Kuala Lumpur)
Endpoint público:
cloudauth-intl.ap-southeast-3.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com
Depuración e integración en línea
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ínimo640*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.NotaLa 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 |
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:
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 |
VerifyModel | String | Sí | [Configuración del producto] Modo de verificación:
| 0 |
TargetFacePicture | String | Obligatorio si | [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 | [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 | [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 | [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 |
FaceRegisterGroupCode | String | Obligatorio si | [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 | [Configuración de la solución de producto - búsqueda 1:N] Si el
| 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) |
|
detección de vida + validación 1:1 |
Inicios de sesión, recuperación de cuentas y confirmación de acciones sensibles. |
|
No aplica |
|
Modo de recuperación |
|
detección de vida + recuperación 1:N |
Prevención de registros duplicados para usuarios nuevos y aplicación de una cuenta por persona. |
|
La detección de vida se aprueba y la recuperación 1:N no encuentra coincidencias. |
|
Modo integral |
|
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 |
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 | |
Result.FaceAttack | String | Indica si se detectó un ataque de suplantación. Valores válidos:
| 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:
| | |
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. | | |
Result.FaceComparisonScore | Double | El resultado de la comparación facial se devuelve cuando | 98 | |
Result.DuplicateFace | String | Devuelve el resultado de la búsqueda de rostros duplicados cuando Los campos devueltos se definen a continuación:
| | |
Result.FaceRegistrationResult | Integer | Resultado del registro facial (se devuelve cuando
| 1 | |
Result.FaceRegistrationId | String | ID del rostro registrado, que se devuelve cuando | 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 |