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

API de Detección de Audio Generado por IA

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

Pruébala sin código visitando nuestro endpoint FastAPI: https://detect-audio.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 Audio IA

Detectar

El flujo de trabajo de detección de audio IA consiste en los siguientes pasos:

  • Obtener una URL de carga pre-firmada
  • Cargar el audio
  • Enviar el audio para detección

1. Obtener una URL de Carga Pre-firmada

Comience solicitando una URL pre-firmada de la API. Esta URL le permite cargar de forma segura su archivo de audio al servidor de almacenamiento.

Formatos de Archivo Soportados

MP3, WAV, M4A, FLAC, OGG, MP4

Nota Importante

Es necesario eliminar espacios del nombre del archivo de audio al solicitar una URL pre-firmada.

GET https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3

Ejemplo de Solicitud

curl -X GET 'https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3' \
--header 'apikey: YOUR API KEY GOES HERE'

Ejemplo de Respuesta

{
  "status": "success",
  "presigned_url": "https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. Cargar el Audio

Use la 'presigned_url' proporcionada para cargar su audio mediante una solicitud PUT. Asegúrese de que el tipo de contenido correcto esté configurado según el formato de su audio.

Nota Importante

Es necesario eliminar espacios del nombre del archivo de audio al cargar el audio.

Ejemplo de Solicitud

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

Límites de Tamaño de Archivo

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

Asegúrese de que el formato del archivo permanezca consistente durante el proceso de carga. Una carga exitosa devolverá un código de estado de 200.

3. Enviar Audio para Detección de IA

Después de cargar, envíe el audio para detección de IA haciendo referencia al 'file_path' del paso anterior.

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

Ejemplo de Solicitud

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

El 'FILE_PATH' se refiere a la ruta obtenida de la respuesta en el paso inicial, 'Obtener una URL de Carga Pre-firmada'.

Parámetros Opcionales

  • analyzeUpToSeconds: Analizar hasta N segundos desde el inicio (predeterminado: 60)
  • document_type: Tipo de documento (predeterminado: 'Audio')
  • 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 para rastrear el estado de la detección.

Consultar Estado y Resultados de la Detección

Para verificar el estado y recuperar los resultados, use el endpoint /query con el ID.

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

Ejemplo de Solicitud

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

Ejemplo de Respuesta

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

Detalles de los Resultados

  • is_valid: Indica si el archivo de audio es válido (true/false)
  • message: Mensaje de procesamiento
  • original_duration: Duración en segundos del audio original
  • is_truncated: Si el audio fue truncado para análisis
  • truncated_duration: Duración analizada si fue truncado
  • mean_ai_prob: Puntuación general de probabilidad de IA
  • individual_chunks_ai_prob: Puntuaciones de probabilidad de IA por chunk

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-audio.truthscan.com/check-user-credits

Ejemplo de Solicitud

curl -X 'GET' \
  'https://detect-audio.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-audio.truthscan.com/health

Ejemplo de Solicitud

curl -X 'GET' \
  'https://detect-audio.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 audio.
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 audio

Solución:

  1. Verifique sus créditos restantes usando /check-user-credits
  2. Compre créditos adicionales si es necesario
  3. Use analyzeUpToSeconds para analizar menos audio y consumir menos créditos

Problemas de Validación de Entrada

"Formato de archivo no soportado" (400)

Causa: Formato de audio no soportado o inválido enviado

Solución:

  1. Verifique que el formato de audio sea soportado (MP3, WAV, M4A, FLAC, OGG, MP4)
  2. Asegúrese de que el archivo no esté corrupto
  3. Verifique el encabezado Content-Type al cargar

"Archivo demasiado grande" (400)

Causa: El tamaño del archivo excede el límite de 10MB

Solución:

  1. Comprima o convierta el audio a menos de 10MB
  2. Verifique el tamaño del archivo antes de cargar
  3. Use formatos más eficientes como MP3 cuando sea posible

Problemas de Procesamiento

"El procesamiento de audio tardó demasiado tiempo"

Causa: El procesamiento del audio tardó demasiado tiempo o ocurrió un timeout

Solución:

  1. Intente con un archivo de audio más pequeño o menor duración
  2. Use analyzeUpToSeconds para analizar solo los primeros segundos
  3. Verifique si el servicio está experimentando alta carga
  4. Vuelva a intentar la solicitud después de unos minutos

Estado "fallido" en la respuesta de /query

Causa: El procesamiento falló por varias razones

Solución:

  1. Verifique si el audio cumple con los requisitos mínimos (1KB - 10MB)
  2. Verifique que el audio esté en un formato soportado
  3. Verifique que la carga se completó exitosamente antes de enviar para detección
  4. Contacte al soporte si el problema persiste

Problemas de Carga

"Fallo en la carga del audio" (403/400)

Causa: URL pre-firmada inválida o expirada, o problemas con el servidor de almacenamiento

Solución:

  1. Asegúrese de usar la URL pre-firmada inmediatamente después de recibirla (puede expirar)
  2. Verifique que el encabezado Content-Type sea correcto para el formato de audio
  3. Elimine espacios del nombre del archivo antes de cargar
  4. Intente generar una nueva URL pre-firmada si la actual expiró

"URL pre-firmada inválida" (400)

Causa: Nombre de archivo con espacios o URL pre-firmada expirada/corrupta

Solución:

  1. Elimine todos los espacios del nombre del archivo antes de solicitar la URL pre-firmada
  2. Use solo caracteres alfanuméricos, guiones y guiones bajos en el nombre del archivo
  3. Genere una nueva URL pre-firmada si es necesario

¿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 audio IA.