Documentación de la API
SOC 2 CertifiedISO 27001GDPR Compliant

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

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 consiste en los siguientes pasos:

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

1. Enviar el Vídeo para Detección

Cargue un archivo de vídeo directamente a la API. 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
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'

Parámetros Opcionales

  • document_type: Tipo de documento (predeterminado: 'Video')
  • email: Dirección de correo electrónico opcional para procesamiento

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 en [0.0, 1.0] 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: Clasificador basado en ConvNeXt 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 los siguientes: "pending" (procesamiento en cola), "analyzing" (detección de IA en progreso), "done" (resultados disponibles), o "failed" (procesamiento falló).

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

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

"No hay créditos suficientes" (403)

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

Solución:

  1. Verifique sus créditos restantes usando /check-user-credits
  2. 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:

  1. Convierta el vídeo a un formato soportado (MP4, MOV, AVI, MKV, WEBM)
  2. 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:

  1. Comprima, recorte o re-codifique el vídeo para reducir el tamaño (máximo 100MB)
  2. 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:

  1. Use un archivo de vídeo más grande (mínimo 1KB)
  2. 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:

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

Problemas de Procesamiento

Estado "fallido" del vídeo

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

Solución:

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

Estado "timeout" del vídeo o procesamiento largo

Causa: El procesamiento del vídeo está tardando más de lo esperado o ha expirado

Solución:

  1. Espere un poco más y verifique el estado nuevamente usando /query
  2. Asegúrese de que el archivo de vídeo cumpla con todos los requisitos de formato y tamaño
  3. Contacte al soporte si el problema persiste

"Usuario no encontrado"

Causa: ID de usuario inválido

Solución:

  1. Verifique que su clave de API sea correcta y esté vinculada a una cuenta activa
  2. Asegúrese de que el usuario de integración sea válido y activo
  3. 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:

  1. Verifique que la carga se completó exitosamente
  2. Verifique que el archivo sea accesible y no esté corrupto
  3. 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.