Documentación de la API

API de Detección de Vídeo Generado por IA

Documentación completa para integrar la API de detección de vídeo IA de TruthScan en sus aplicaciones.

Pruébala sin código visitando nuestro endpoint FastAPI: https://detect-video.truthscan.com/docs

Precios y créditos

Cada solicitud de detección de video consume créditos de su cuenta cuando el procesamiento finaliza.

Consulte su saldo con GET /check-user-credits. Ver planes de precios

Autenticación

TruthScan usa claves de API para permitir el acceso a la API. Puede obtener su clave de API en la parte superior de la página en nuestro portal de desarrolladores.

TruthScan espera que la clave de API se incluya en todas las solicitudes de API al servidor en un cuerpo de solicitud que se ve así:

{
  "key": "YOUR API KEY GOES HERE"
}

Debe reemplazar YOUR API KEY GOES HERE con su clave de API personal.

Detector de Vídeo IA

Detectar (Proceso de 2 Pasos)

El flujo de trabajo de detección de vídeo IA consta de dos pasos:

Enviar el vídeo para detección (carga multipart o URL)
Consultar el trabajo para recuperar resultados

Modelos de Detección

Seleccione qué modelo ML se ejecuta durante el pipeline de detección usando el parámetro opcional model. Si se omite, se usa generic.

generic: Modelo de detección general de vídeo IA (predeterminado)
faceswap: Modelo dedicado de detección de vídeos Face Swap

Ambos modelos usan el mismo pipeline de detección (metadata → watermark → ML) y devuelven el mismo formato de respuesta. Los valores inválidos de model devuelven 422.

1. Enviar el Vídeo

Cargue un archivo de vídeo directamente a la API o envíe una URL de vídeo. El servidor validará el archivo.

Formatos de Archivo Soportados

mp4, mov, avi, mkv, webm

Límites de Tamaño de Archivo

Tamaño mínimo de archivo: 1KB
Tamaño máximo de archivo: 100MB

Enviar mediante carga de archivo

Headers

key (obligatorio): Su clave de API
email: Dirección de correo electrónico opcional
userkey: Clave de usuario de integración opcional

Multipart form-data

file (obligatorio): El vídeo a analizar
model: Modelo de detección a usar, es decir, generic o faceswap (opcional, predeterminado: generic)

POST https://detect-video.truthscan.com/detect-file

Ejemplo de Solicitud

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Ejemplo con modelo Face Swap

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4' \
  -F 'model=faceswap'

Parámetros Opcionales

document_type: Tipo de documento (predeterminado: Video)
email: Dirección de correo electrónico para procesamiento
model: Modelo de detección, es decir, generic o faceswap (predeterminado: generic)

Enviar mediante URL

Headers

Content-Type: application/json

Body (JSON)

key (obligatorio): Su clave de API
url: https://ai-video-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>
model: Modelo de detección a usar, es decir, generic o faceswap (opcional, predeterminado: generic)

POST https://detect-video.truthscan.com/detect

Ejemplo de Solicitud

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "generic"
}'

Ejemplo con modelo Face Swap

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "faceswap"
}'

Parámetros Opcionales

document_type: Tipo de documento (predeterminado: Video)
email: Dirección de correo electrónico para procesamiento
model: Modelo de detección, es decir, generic o faceswap (predeterminado: generic)

Ejemplo de Respuesta

{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
  "status": "pending"
}

La respuesta incluye un ID único de vídeo para rastrear el estado de la detección.

2. Consultar Estado y Resultados de la Detección

Después de enviar, consulte el endpoint /query con el ID del trabajo para recuperar estado y resultados.

POST https://detect-video.truthscan.com/query

Ejemplo de Solicitud

curl -X POST 'https://detect-video.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"id":"JOB-ID-GOES-HERE"}'

Ejemplo de Respuesta

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Detalles de los Resultados

status: "pending", "analyzing", "done", o "failed"
result: Puntuación escalar de probabilidad IA en [0.0, 1.0] (valores más altos = más probable que sea generado por IA), derivada de ML prob_fake
final_stage: Última etapa que contribuyó al resultado: 'metadata', 'watermark' o 'ml'
metadata: Siempre establece prediction: 'no_detection' y confidence: 0.0. El estado puede ser 'reject', 'reencode' o 'ok'
watermark: Heurística que muestrea frames y calcula confianza pseudo a partir de la varianza de píxeles
ml: Modelo clasificador ejecutado en frames muestreados. Devuelve prob_fake en [0.0, 1.0] y label ('ai_generated' si prob_fake ≥ 0.5, de lo contrario 'no_detection')
latency_sec: Tiempo total del pipeline

El campo "status" será uno de: "pending" (procesamiento en cola), "analyzing" (detección de IA en progreso), "done" (resultados disponibles), o "failed" (procesamiento fallido).

Verificar Créditos del Usuario

Este endpoint acepta el apikey del usuario a través del encabezado. Y devuelve los detalles de créditos del usuario.

GET https://detect-video.truthscan.com/check-user-credits

Ejemplo de Solicitud

curl -X 'GET' \
  'https://detect-video.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Ejemplo de Respuesta

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Verificación de Salud

Verifique el estado de salud del servidor de la API.

GET https://detect-video.truthscan.com/health

Ejemplo de Solicitud

curl -X 'GET' \
  'https://detect-video.truthscan.com/health' \
  -H 'accept: application/json'

Ejemplo de Respuesta

{
  "status": "healthy"
}

Errores

La mayoría de los errores serán por parámetros incorrectos enviados a la API. Verifique nuevamente los parámetros de cada llamada de API para asegurarse de que esté formateado correctamente e intente ejecutar el código de ejemplo proporcionado.

Los códigos de error genéricos que usamos se ajustan al estándar REST:

Código de Error	Significado
400	Bad Request -- Su solicitud es inválida.
403	Forbidden -- La clave de API es inválida o no hay créditos suficientes para procesamiento de vídeo.
404	Not Found -- El recurso especificado no existe.
405	Method Not Allowed -- Intentó acceder a un recurso con un método inválido.
406	Not Acceptable -- Solicitó un formato que no es JSON.
410	Gone -- El recurso en este endpoint ha sido eliminado.
422	Invalid Request Body -- El cuerpo de su solicitud está formateado incorrectamente o es inválido o tiene parámetros faltantes.
429	Too Many Requests -- ¡Está enviando demasiadas solicitudes! ¡Reduzca la velocidad!
500	Internal Server Error -- Tuvimos un problema con nuestro servidor. Intente nuevamente más tarde.
503	Service Unavailable -- Estamos temporalmente fuera de línea para mantenimiento. Intente nuevamente más tarde.

Problemas Comunes y Soluciones

Problemas de Autenticación

"Verificación de usuario fallida" (403)

Causa: Clave de API inválida o expirada

Solución:

Verifique que su clave de API sea correcta
Verifique si su clave de API está activa en su cuenta
Intente regenerar su clave de API

"No hay créditos suficientes" (403)

Causa: Créditos insuficientes para procesamiento de vídeo

Solución:

Verifique sus créditos restantes usando /check-user-credits
Compre créditos adicionales si es necesario

Problemas de Validación de Entrada

"Tipo de vídeo no soportado" (400)

Causa: Formato de vídeo no soportado

Solución:

Convierta el vídeo a un formato soportado (MP4, MOV, AVI, MKV, WEBM)
Asegúrese de que la extensión del archivo y el tipo MIME sean correctos

"El tamaño del archivo excede el límite" (400)

Causa: El archivo de vídeo es demasiado grande

Solución:

Comprima, recorte o re-codifique el vídeo para reducir el tamaño (máximo 100MB)
Use un códec/contenedor más eficiente

"El tamaño del archivo es demasiado pequeño" (400)

Causa: El archivo de vídeo está por debajo del requisito de tamaño mínimo

Solución:

Use un archivo de vídeo más grande (mínimo 1KB)
Verifique si el archivo fue corrupto durante la carga

"Tipo de archivo inválido" (400)

Causa: La validación del tipo de archivo falló (por ejemplo, tipo MIME incorrecto o archivo corrupto)

Solución:

Asegúrese de que el archivo sea un formato de vídeo válido
Verifique que el tipo MIME coincida con la extensión del archivo
Re-exporte o re-codifique el archivo si es necesario

Valor de model inválido (422)

Causa: El parámetro model no es generic o faceswap

Solución:

Omita model para usar el modelo generic predeterminado
Establezca model como generic para detección general de vídeo IA
Establezca model como faceswap para detección de vídeos Face Swap

Problemas de Procesamiento

Estado "fallido" del vídeo

Causa: El procesamiento falló (por ejemplo, contenedor ilegible, errores de decodificación)

Solución:

Asegúrese de que el contenedor/códec sea comúnmente soportado (H.264/AAC en MP4 recomendado)
Re-codifique el vídeo usando un preset estándar (por ejemplo, ffmpeg) y vuelva a cargar
Asegúrese de que el archivo cumpla con los requisitos de tamaño y formato
Contacte al soporte si el problema persiste

"Usuario no encontrado"

Causa: ID de usuario inválido

Solución:

Verifique que su clave de API sea correcta y esté vinculada a una cuenta activa
Asegúrese de que el usuario de integración sea válido y activo
Re-autentique si es necesario

"No se pudieron obtener los metadatos del archivo" (500)

Causa: No se pudo acceder o analizar el archivo cargado

Solución:

Verifique que la carga se completó exitosamente
Verifique que el archivo sea accesible y no esté corrupto
Intente volver a cargar el archivo

¿Necesita Ayuda?

Para obtener más información sobre cómo usar nuestra API o para soporte técnico, contáctenos.

Contáctenos

Preguntas Frecuentes sobre la API

Encuentre respuestas a las preguntas más comunes sobre nuestra API de detección de vídeo IA.