> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detección de deepfake y suplantación

> Evalúe los indicadores de falsificación profunda e suplantación de identidad o las puntuaciones externas proporcionadas, y dirija los resultados del umbral a las señales de riesgo.

> [!WARNING]
>
> Este punto final no descarga ni inspecciona la imagen, el video o el documento referenciados. Califica los indicadores o las puntuaciones proporcionadas por su aplicación. Los valores son puntuaciones de riesgo heurísticas, no probabilidades calibradas. La etiqueta `authentic` significa que no se alcanzó el umbral de riesgo configurado; no es prueba de que el medio sea auténtico, especialmente cuando no se proporcionaron indicadores.

La API de deepfake e suplantación evalúa indicadores o puntuaciones externas proporcionadas por su aplicación para un sujeto referenciado. No inspecciona el medio o documento referenciado. Los resultados que superan el umbral de riesgo crean automáticamente una [señal de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md), conectando su evidencia de detección ascendente a la tubería del Firewall de Identidad Antifraude.

> [!NOTE]
>
> La detección de deepfake es parte del [Firewall de identidad antifraude](https://docs.truthlocks.com/es/guides/risk-signals.md). Los resultados del escaneo fluyen a la misma tubería de señales de riesgo que otras señales de fraude, por lo que puede consultarlos y revisarlos desde la página de la consola **Riesgo y fraude > Señales** o el [punto final de lista de señales](https://docs.truthlocks.com/es/api-reference/risk-signals/list.md).

## Cómo funciona

**1. Enviar un escaneo**

Envíe una solicitud `POST` a `/v1/risk/deepfake/scan` con una referencia de sujeto y señales de indicador sin procesar de su pipeline de detección o puntuaciones precalculadas de un modelo externo.

**2. Revisar el veredicto**

La respuesta incluye puntuaciones de deepfake e impersonación (0-100) y un veredicto: `authentic`, `suspect`, `deepfake` o `impersonation`.

**3. Creación automática de señales**

Cuando una puntuación alcanza 60 o más, la plataforma ingiere automáticamente una señal de riesgo en el pipeline de su inquilino. La respuesta incluye el `signal_id` para que pueda rastrearlo.

**4. Recuperar resultados más tarde**

Utilice `GET /v1/risk/deepfake/results/{subject_ref}` para obtener el resultado de escaneo más reciente de cualquier sujeto escaneado previamente.

## Requisitos previos

* Un inquilino activo de Truthlocks con una clave API
* Referencias de asunto para el contenido que desea escanear (URL, hashes SHA-256, ID de atestación o identificadores opacos)

## Escaneo de un sujeto

Envíe un escaneo con señales indicadoras de su canal de detección:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "image",
    "signals": ["face_swap_detected", "inconsistent_lighting"]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/deepfake/scan", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_ref: "sha256:a1b2c3d4...",
    subject_type: "image",
    signals: ["face_swap_detected", "inconsistent_lighting"],
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/deepfake/scan",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_ref": "sha256:a1b2c3d4...",
        "subject_type": "image",
        "signals": ["face_swap_detected", "inconsistent_lighting"],
    },
)
result = resp.json()
```

La respuesta incluye puntuaciones, un veredicto y (si se cumplió el umbral) una señal de riesgo vinculada:

```json theme={null}
{
  "scan_id": "7c8d9e0f-...",
  "subject_ref": "sha256:a1b2c3d4...",
  "subject_type": "image",
  "deepfake_score": 60,
  "impersonation_score": 0,
  "verdict": "suspect",
  "indicators": ["face_swap_detected", "inconsistent_lighting"],
  "detection_model": "heuristic_v1",
  "signal_id": "9f3a1c2d-...",
  "created_at": "2027-05-22T10:00:00Z"
}
```

## Modelo de detección

La plataforma utiliza un motor de señales heurísticas (`heuristic_v1`) que mapea los indicadores proporcionados por el llamador a puntuaciones ponderadas. El motor evalúa 12 indicadores en dos categorías:

### Indicadores de deepfake

| Indicador | Descripción |
| :- | :- |
| `face_swap_detected` | Se detectó reemplazo o morphing de cara |
| `inconsistent_lighting` | Inconsistencias de iluminación en el sujeto |
| `compression_artifacts` | Patrones de compresión inusuales que sugieren manipulación |
| `temporal_inconsistency` | Inconsistencias a nivel de fotograma en el contenido de video |
| `metadata_mismatch` | Los metadatos del archivo no coinciden con los patrones esperados |

### Indicadores de suplantación

| Indicador | Descripción |
| :- | :- |
| `biometric_mismatch` | Los datos biométricos no coinciden con la identidad declarada |
| `name_mismatch` | El nombre en el documento de identidad no coincide con los registros |
| `identity_doc_mismatch` | El documento de identidad parece alterado o inconsistente |
| `issuer_trust_violation` | El nivel de confianza del emisor es insuficiente para la reclamación |

## Veredictos y umbrales

Cada escaneo produce un veredicto basado en la puntuación más alta:

| Rango de puntuación | Veredicto | Significado |
| :- | :- | :- |
| 0 – 39 | `authentic` | No se detectaron indicadores significativos |
| 40 – 74 | `suspect` | Algunos indicadores presentes — se recomienda revisión |
| 75 – 100 | `deepfake` o `impersonation` | Detección de alta confianza — el veredicto depende de la puntuación dominante |

Cuando cualquiera de las puntuaciones alcanza **60 o más**, la plataforma crea automáticamente una señal de riesgo. No necesita realizar una llamada a la API separada; el `signal_id` se devuelve en la respuesta del escaneo.

## Uso de puntuaciones precalculadas

Si ya tiene puntuaciones de un modelo de ML externo o un servicio de detección, páselas directamente para omitir el análisis heurístico:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "video",
    "deepfake_score": 82,
    "impersonation_score": 15
  }'
```

La plataforma sigue aplicando los mismos umbrales de veredicto y la ingesta automática de señales, por lo que obtendrá una clasificación consistente independientemente de la fuente de detección.

## Vinculación de escaneos a atestaciones

Asocie un escaneo con una atestación existente para vincular los resultados de detección con la credencial a la que se relacionan:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "attestation",
    "signals": ["biometric_mismatch", "identity_doc_mismatch"],
    "attestation_id": "660e8400-e29b-41d4-a716-446655440001"
  }'
```

Esto facilita la señalización y revisión de atestaciones sospechosas en la consola.

## Recuperación de resultados de escaneo

Obtener el último resultado de escaneo para un sujeto sin volver a ejecutar el escaneo:

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/deepfake/results/sha256:a1b2c3d4... \
  -H "X-API-Key: tl_live_..."
```

## Tipos de sujetos

El campo `subject_type` le indica a la plataforma qué tipo de contenido se está escaneando:

| Tipo | Caso de uso |
| :- | :- |
| `image` | Fotos, documentos de identidad, fotos de perfil |
| `video` | Grabaciones de video, capturas en vivo |
| `document` | PDFs, documentos escaneados |
| `attestation` | Credenciales emitidas a través de la plataforma |
| `identity` | Reclamaciones de identidad, envíos KYC |

## Medición de uso

Cada solicitud de escaneo de deepfake incrementa el contador de uso de `antifraud.deepfake_scans` para su ciclo de facturación. Puede monitorear su consumo de escaneo con la [API de uso](https://docs.truthlocks.com/es/api-reference/billing/usage.md) o en la consola en **Configuración > Facturación > Uso** en la sección **Antifraude**.

> [!NOTE]
>
> Las cuotas de escaneo de deepfake varían según el nivel del plan. Consulte la [descripción general de la facturación](https://docs.truthlocks.com/es/billing/overview.md#metered-products) para obtener detalles sobre todos los productos medidos antifraude.

## Qué sigue

* [Referencia de la API de escaneo de deepfake](https://docs.truthlocks.com/es/api-reference/risk/deepfake-scan.md)
* [Referencia de la API de obtención de resultados de escaneo](https://docs.truthlocks.com/es/api-reference/risk/deepfake-results.md)
* [Guía de detección de toma de control de cuentas](https://docs.truthlocks.com/es/guides/ato-detection.md)
* [Guía de puntuación de velocidad y anomalías](https://docs.truthlocks.com/es/guides/velocity-scoring.md)
* [Guía de señales de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md)
* [Referencia de la API de ingesta de señal de riesgo](https://docs.truthlocks.com/es/api-reference/risk/ingest-signal.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.