> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API de comparación facial 1:1: Face Match > API Face Match de Didit: POST /v3/face-match/ compara dos rostros 1:1 en menos de 2 s. Pago por uso, sin mínimos mensuales. ## OpenAPI ````yaml es/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Coincidencia facial description: >- Compara dos imágenes faciales (1:1) y obtén una `score` de similitud (0–100) junto con un `status` `Approved`/`Declined`. **Cómo funciona.** Ambas imágenes se decodifican y las analiza un modelo biométrico (configura `rotate_image=true` si las capturas pueden estar de lado o boca abajo); después se calcula una puntuación de similitud entre los dos rostros. Una puntuación **estrictamente superior** a `face_match_score_decline_threshold` (por defecto `30`) devuelve `status: "Approved"`; una puntuación igual o inferior devuelve `Declined` con una advertencia `LOW_FACE_MATCH_SIMILARITY`. Si no se puede puntuar ningún par de rostros, la llamada igualmente devuelve `200` con `status: "Declined"` y una advertencia `NO_REFERENCE_IMAGE`: `score` es `null` en la ruta de guardado predeterminada, o `0` con `save_api_request=false`. Para obtener los mejores resultados, envía un único rostro nítido y de frente por imagen. **Facturación.** Cada respuesta `200` consume un crédito de la API de Face Match (pagado con el crédito de tu plan o con tu saldo recargado). Cuando el saldo de la organización no alcanza para cubrir la llamada, el endpoint devuelve `403` con el error de créditos insuficientes antes de procesar ninguna imagen. **Persistencia de la sesión (`save_api_request`, por defecto `true`).** Cuando es `true`, la llamada se guarda como una sesión de tipo API: aparece en la Business Console, el `request_id` devuelto es un ID de sesión real que puedes pasar a `GET /v3/session/{sessionId}/decision/`, ambas imágenes se almacenan como las imágenes de origen y destino de la coincidencia facial de la sesión, y se emite un webhook `status.updated` a los endpoints de webhook que hayas configurado. Cuando es `false`, no se almacena nada y `request_id` es un UUID de correlación de un solo uso que no se puede consultar después. **Índice de búsqueda facial.** Este endpoint nunca inscribe rostros en tu índice de búsqueda facial y nunca ejecuta comprobaciones de lista de bloqueo ni de duplicados: usa `POST /v3/passive-liveness/` o `POST /v3/face-search/` para ello. **Sandbox.** Las claves de API de sandbox omiten todo el procesamiento y la facturación: tras la validación de la solicitud (una entrada mal formada sigue devolviendo `400`), el endpoint devuelve un payload simulado estático `Approved`, no se guarda ninguna sesión y no se consumen créditos. **Autenticación.** Envía la clave de API de tu aplicación en el encabezado `x-api-key`. Las credenciales ausentes o no válidas devuelven `403` (`{"detail": "You do not have permission to perform this action."}`): esta API nunca devuelve `401`. **Límite de solicitudes.** Cupo de escritura compartido de 300 solicitudes/min por clave de API entre todos los endpoints POST/PATCH/DELETE; si se supera, se devuelve `429`. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Imagen del rostro real o candidato que se va a verificar (p. ej., una selfie). Envía una única foto de frente con el rostro de la persona claramente visible y bien iluminado. Extensiones permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamaño máximo de subida: **5 MB** (los archivos más grandes se rechazan con `400`). Las imágenes se comprimen automáticamente a ~0.5 MB antes del procesamiento, por lo que las resoluciones muy altas no mejoran la precisión. ref_image: type: string format: binary description: >- Imagen facial de referencia con la que comparar (p. ej., el retrato de un documento de identidad o una foto registrada previamente). Tiene los mismos límites de formato y tamaño que `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Umbral de similitud (0–100) que determina el `status` de la respuesta. Una puntuación calculada **igual o inferior** a este valor establece `status` en `Declined` y añade una advertencia `LOW_FACE_MATCH_SIMILARITY`; una puntuación estrictamente superior devuelve `Approved`. El valor predeterminado `30` es permisivo: súbelo (p. ej., `50`–`60`) para una verificación más estricta. Los valores fuera de 0–100 devuelven `400`. example: 50 rotate_image: type: boolean default: false description: >- Si es `true`, el servicio prueba las imágenes de entrada en incrementos de 90 grados (0, 90, 180, 270) y usa la orientación que ofrece la mejor detección facial, algo útil para capturas desde el móvil sin orientación EXIF. Añade latencia, así que actívalo solo si no puedes garantizar imágenes en posición vertical. example: false save_api_request: type: boolean default: true description: >- Cuando es `true` (valor predeterminado), guarda la llamada como una sesión de tipo API: visible en la Business Console, recuperable mediante `GET /v3/session/{sessionId}/decision/` con el `request_id` devuelto y notificada mediante un webhook `status.updated`. Cuando es `false`, no se almacena nada y `request_id` es un UUID temporal que solo sirve para correlacionar la respuesta. example: true vendor_data: type: string description: >- Cadena opaca opcional (tu ID de usuario interno, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve en la respuesta. Úsala para relacionar las llamadas a la API con tus propios registros y para filtrar sesiones más adelante. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional que se almacena con la sesión (cuando `save_api_request=true`) y se devuelve en la respuesta. En solicitudes multipart, envíalo como un campo de cadena codificado en JSON (p. ej., `metadata={"flow":"login"}`): se convierte en un objeto. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Coincidencia facial calculada. `face_match.score` es un número decimal de 0 a 100 (dos decimales); `status` es `Approved` cuando la puntuación es estrictamente superior a `face_match_score_decline_threshold`; en caso contrario, es `Declined` con una advertencia explicativa. Una similitud baja o un par imposible de puntuar también devuelve `200`: revisa `face_match.status` y `face_match.warnings`, no solo el código HTTP. Cuando `save_api_request=true`, `request_id` es el ID de la sesión guardada. content: application/json: examples: Approved: summary: 'Misma persona: puntuación por encima del umbral' value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Puntuación igual o inferior al umbral de rechazo value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID de la sesión guardada cuando `save_api_request=true` (se puede usar con `GET /v3/session/{sessionId}/decision/`); en caso contrario, un UUID de correlación temporal. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` cuando la puntuación de similitud es estrictamente superior a `face_match_score_decline_threshold` y se pudo calcular una puntuación; `Declined` en caso contrario (una advertencia explica el motivo). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuación de similitud de 0 a 100: la confianza del modelo en que ambas imágenes muestran a la misma persona. Se redondea a dos decimales solo cuando `save_api_request` es true; con `save_api_request=false` se devuelve el float sin redondear. `null` cuando no se pudo puntuar ningún par de rostros (con el valor predeterminado `save_api_request=true`); con `save_api_request=false` la misma condición puede aparecer como `score: 0`. En cualquier caso, hay una advertencia `NO_REFERENCE_IMAGE` y `status` es `Declined`. example: 99.41 user_image: type: object description: >- Resultados de la detección facial de las imágenes analizadas. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Cuadro delimitador del rostro detectado, en coordenadas de píxeles `[x_min, y_min, x_max, y_max]` de la imagen procesada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confianza de la detección facial (0–1). example: 0.732973 age: type: number format: float description: >- Edad del rostro detectado estimada por el modelo, en años. Solo es informativa: no afecta a la decisión de coincidencia facial. example: 26.91 gender: type: string description: >- Género del rostro detectado predicho por el modelo (`male` o `female`). Solo es informativo. example: male race: type: string nullable: true description: >- Campo reservado: siempre es `null` en las respuestas de este endpoint. example: null description: Una entrada por rostro detectado. best_angle: type: integer description: >- Rotación (en grados: 0, 90, 180 o 270) que produjo la mejor detección facial. Solo es distinta de cero cuando `rotate_image=true` corrigió la orientación. example: 0 ref_image: type: object description: >- Resultados de la detección facial de la imagen de referencia, con la misma estructura que `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Cuadro delimitador del rostro detectado, en coordenadas de píxeles `[x_min, y_min, x_max, y_max]` de la imagen procesada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confianza de la detección facial (0–1). example: 0.732973 age: type: number format: float description: >- Edad del rostro detectado estimada por el modelo, en años. Solo es informativa: no afecta a la decisión de coincidencia facial. example: 26.91 gender: type: string description: >- Género del rostro detectado predicho por el modelo (`male` o `female`). Solo es informativo. example: male race: type: string nullable: true description: >- Campo reservado: siempre es `null` en las respuestas de este endpoint. example: null description: Una entrada por rostro detectado. best_angle: type: integer example: 0 warnings: type: array description: >- Vacío en una aprobación sin incidencias. `NO_REFERENCE_IMAGE` (`error`): no se pudo puntuar ningún par de rostros; `LOW_FACE_MATCH_SIMILARITY` (`error`): puntuación igual o inferior al umbral de rechazo. Cualquiera de ellas establece `status` en `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Código de riesgo legible por máquina. feature: type: string enum: - FACEMATCH description: >- Función que emitió la advertencia. En este endpoint siempre es `FACEMATCH`. additional_data: type: object nullable: true additionalProperties: true description: >- Siempre `null` en las advertencias de coincidencia facial. log_type: type: string enum: - error - warning - information description: >- Gravedad. Las advertencias `error` llevan `status` a `Declined`; las entradas `warning` e `information` son informativas y nunca rechazan por sí solas. short_description: type: string description: Resumen legible del riesgo en una línea. long_description: type: string description: Explicación legible del riesgo. vendor_data: type: string nullable: true description: Devuelve el `vendor_data` que enviaste, o `null`. metadata: type: object nullable: true additionalProperties: true description: Devuelve el objeto `metadata` que enviaste, o `null`. created_at: type: string format: date-time description: >- Marca de tiempo ISO 8601 (UTC) del momento en que se generó la respuesta, p. ej., `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Error de validación. Se devuelve cuando falta una imagen obligatoria, supera los 5 MB o tiene una extensión no admitida, o cuando una opción está fuera de rango. El cuerpo es el formato estándar de errores de campo de DRF: un array de mensajes por cada campo con error. content: application/json: examples: Missing required image: summary: >- `ref_image` (o `user_image`) no está incluido en los datos del formulario value: ref_image: - No file was submitted. Unsupported file extension: summary: Extensión de archivo distinta de tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: El archivo supera el límite de 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_match_score_decline_threshold` fuera del rango 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Permiso denegado. Se devuelve cuando falta el encabezado `x-api-key` y también cuando el saldo de la organización que realiza la llamada no la cubre; una clave incorrecta, revocada o expirada devuelve `401`. Si falta la clave, se devuelve `403` con `{"detail": ...}`; una clave incorrecta, revocada o expirada devuelve `401`. La falta de créditos devuelve `403` con `{"error": ...}` antes de que se procese ninguna imagen. content: application/json: examples: Missing or invalid API key: summary: >- Falta el encabezado `x-api-key`, o la clave no es válida o está revocada value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de la organización no cubre la llamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Límite de solicitudes superado. Todos los endpoints POST/PATCH/DELETE comparten un presupuesto de 300 solicitudes de escritura por minuto por clave de API. La respuesta incluye los encabezados `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` y `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Más de 300 solicitudes de escritura en el minuto actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.