> ## 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.

# Detecção de deepfake e personificação

> Avalia indicadores de deepfake e personificação fornecidos ou pontuações externas, e encaminha os resultados do limite para sinais de risco.

> [!WARNING]
>
> Este endpoint não baixa nem inspeciona a imagem, vídeo ou documento referenciado. Ele pontua indicadores ou pontuações fornecidas pelo seu aplicativo. Os valores são pontuações de risco heurísticas, não probabilidades calibradas. O rótulo `authentic` significa que o limite de risco configurado não foi atingido; não é prova de que a mídia é autêntica, especialmente quando nenhum indicador foi fornecido.

A API de deepfake e personificação avalia indicadores ou pontuações externas fornecidas por sua aplicação para um assunto referenciado. Ela não inspeciona a mídia ou o documento referenciado. Resultados que excedem o limite de risco criam automaticamente um [sinal de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md), conectando sua evidência de detecção upstream ao pipeline do Firewall de Identidade Antifraude.

> [!NOTE]
>
> A detecção de deepfake faz parte do [Firewall de Identidade Antifraude](https://docs.truthlocks.com/pt/guides/risk-signals.md). Os resultados da varredura fluem para o mesmo pipeline de sinal de risco que outros sinais de fraude, para que você possa consultá-los e revisá-los na página do console **Risco e Fraude > Sinais** ou no [endpoint de listagem de sinais](https://docs.truthlocks.com/pt/api-reference/risk-signals/list.md).

## Como funciona

**1. Enviar uma digitalização**

Envie uma solicitação `POST` para `/v1/risk/deepfake/scan` com uma referência de assunto e sinais indicadores brutos do seu pipeline de detecção ou pontuações pré-calculadas de um modelo externo.

**2. Revisar o veredito**

A resposta inclui pontuações de deepfake e personificação (0–100) e um veredito: `authentic`, `suspect`, `deepfake` ou `impersonation`.

**3. Criação automática de sinais**

Quando uma pontuação atinge 60 ou mais, a plataforma ingere automaticamente um sinal de risco na pipeline do seu locatário. A resposta inclui o `signal_id` para que você possa rastreá-lo.

**4. Recuperar resultados mais tarde**

Use `GET /v1/risk/deepfake/results/{subject_ref}` para buscar o resultado da varredura mais recente para qualquer assunto previamente varrido.

## Pré-requisitos

* Um inquilino Truthlocks ativo com uma chave de API
* Referências de assunto para o conteúdo que você deseja escanear (URLs, hashes SHA-256, IDs de atestação ou identificadores opacos)

## Escaneando um assunto

Envie uma digitalização com sinais indicadores do seu pipeline de detecção:

```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()
```

A resposta inclui pontuações, um veredito e (se o limite for atingido) um sinal de risco vinculado:

```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 detecção

A plataforma usa um mecanismo de sinal heurístico (`heuristic_v1`) que mapeia indicadores fornecidos pelo chamador para pontuações ponderadas. O mecanismo avalia 12 indicadores em duas categorias:

### Indicadores de deepfake

| Indicador | Descrição |
| :- | :- |
| `face_swap_detected` | Substituição ou morphing de rosto detetado |
| `inconsistent_lighting` | Inconsistências de iluminação no sujeito |
| `compression_artifacts` | Padrões de compressão incomuns sugerindo manipulação |
| `temporal_inconsistency` | Inconsistências ao nível do frame no conteúdo de vídeo |
| `metadata_mismatch` | Os metadados do ficheiro não correspondem aos padrões esperados |

### Indicadores de personificação

| Indicador | Descrição |
| :- | :- |
| `biometric_mismatch` | Os dados biométricos não correspondem à identidade declarada |
| `name_mismatch` | Nome no documento de identidade não corresponde aos registros |
| `identity_doc_mismatch` | Documento de identidade parece alterado ou inconsistente |
| `issuer_trust_violation` | Nível de confiança do emissor é insuficiente para a reivindicação |

## Vereditos e limites

Cada varredura produz um veredito baseado na pontuação mais alta:

| Faixa de pontuação | Veredito | Significado |
| :- | :- | :- |
| 0 – 39 | `authentic` | Nenhum indicador significativo detectado |
| 40 – 74 | `suspect` | Alguns indicadores presentes — revisão recomendada |
| 75 – 100 | `deepfake` ou `impersonation` | Deteção de alta confiança — qual veredito depende da pontuação dominante |

Quando qualquer uma das pontuações atinge **60 ou mais**, a plataforma cria automaticamente um sinal de risco. Você não precisa fazer uma chamada de API separada — o `signal_id` é retornado na resposta da varredura.

## Usando pontuações pré-calculadas

Se você já tiver pontuações de um modelo ML externo ou serviço de detecção, passe-as diretamente para pular a análise heurística:

```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
  }'
```

A plataforma ainda aplica os mesmos limites de veredito e ingestão automática de sinais, para que você obtenha uma classificação consistente, independentemente da fonte de detecção.

## Vinculando varreduras a atestações

Associe uma digitalização a uma atestação existente para vincular os resultados da deteção à credencial a que se referem:

```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"
  }'
```

Isso facilita a sinalização e revisão de atestados suspeitos no console.

## Recuperando resultados de varredura

Obtenha o resultado da análise mais recente para um assunto sem executar novamente a análise:

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

## Tipos de assunto

O campo `subject_type` informa à plataforma que tipo de conteúdo está sendo escaneado:

| Tipo | Caso de uso |
| :- | :- |
| `image` | Fotos, documentos de identidade, fotos de perfil |
| `video` | Gravações de vídeo, capturas ao vivo |
| `document` | PDFs, documentos digitalizados |
| `attestation` | Credenciais emitidas através da plataforma |
| `identity` | Declarações de identidade, envios KYC |

## Medição de uso

Cada solicitação de varredura de deepfake incrementa o contador de uso `antifraud.deepfake_scans` para o seu ciclo de faturamento. Você pode monitorar seu consumo de varredura com a [API de uso](https://docs.truthlocks.com/pt/api-reference/billing/usage.md) ou no console em **Configurações > Faturamento > Uso** na seção **Anti-Fraude**.

> [!NOTE]
>
> As cotas de varredura de deepfake variam de acordo com o nível do plano. Consulte a [visão geral de faturamento](https://docs.truthlocks.com/pt/billing/overview.md#metered-products) para obter detalhes sobre todos os produtos antifraude medidos.

## O que vem a seguir

* [Referência da API de varredura de deepfake](https://docs.truthlocks.com/pt/api-reference/risk/deepfake-scan.md)
* [Obter referência da API de resultados de varredura](https://docs.truthlocks.com/pt/api-reference/risk/deepfake-results.md)
* [Guia de detecção de aquisição de conta](https://docs.truthlocks.com/pt/guides/ato-detection.md)
* [Guia de pontuação de velocidade e anomalias](https://docs.truthlocks.com/pt/guides/velocity-scoring.md)
* [Guia de sinais de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md)
* [Ingerir referência da API de sinal de risco](https://docs.truthlocks.com/pt/api-reference/risk/ingest-signal.md)


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