API de Detección de Imagen Generada por IA
Documentación completa para integrar la API de detección de imagen IA de TruthScan en sus aplicaciones.
Pruébala sin código visitando nuestro endpoint FastAPI: https://detect-image.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 Imagen IA
Detectar
El flujo de trabajo de detección de imagen IA consiste en los siguientes pasos:
- Obtener una URL de carga pre-firmada
- Cargar la imagen
- Enviar la imagen 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 imagen al servidor de almacenamiento.
Formatos de Archivo Soportados
JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF
Nota Importante
Es necesario eliminar espacios del nombre del archivo de imagen al solicitar una URL pre-firmada.
GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpgEjemplo de Solicitud
curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'Ejemplo de Respuesta
{
"status": "success",
"presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
"file_path": "uploads/example.jpg"
}2. Cargar la Imagen
Use la 'presigned_url' proporcionada para cargar su imagen mediante una solicitud PUT. Asegúrese de que el tipo de contenido correcto esté configurado según el formato de su imagen.
Nota Importante
Es necesario eliminar espacios del nombre del archivo de imagen al cargar la imagen.
Ejemplo de Solicitud
curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
--header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
--header 'x-amz-acl: private' \
--data-binary '@example.jpg' # AttachmentLí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 Imagen para Detección de IA
Después de cargar, envíe la imagen para detección de IA haciendo referencia al 'file_path' del paso anterior.
POST https://detect-image.truthscan.com/detectEjemplo de Solicitud
curl -X 'POST' \
'https://detect-image.truthscan.com/detect' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"key": "YOUR-API-KEY-GOES-HERE",
"url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
"generate_preview": false
}'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
generate_preview: Establecer como 'true' para generar una URL de vista previa de la imagen (predeterminado: 'false')document_type: Tipo de documento (predeterminado: 'Image')email: Dirección de correo electrónico para procesamiento
Ejemplo de Respuesta
{
"id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
"status": "pending"
}La respuesta incluye un ID único de imagen para rastrear el estado de la detección.
Consultar
Este endpoint acepta un ID de imagen devuelto por la solicitud /detect. Y devuelve el estado del envío de la imagen, así como el resultado completo de la operación de detección de IA, incluyendo metadatos, OCR y análisis del modelo ML.
POST https://detect-image.truthscan.com/queryEjemplo de Solicitud
curl -X 'POST' \
'https://detect-image.truthscan.com/query' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id": "IMAGE-ID-GOES-HERE"
}'Ejemplo de Respuesta
{
"id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
"status": "done",
"result": 90.2371538185235,
"result_details": {
"is_valid": true,
"detection_step": 3,
"final_result": "AI Generated",
"metadata": [
"No Information Detected for Real/AI",
"Could not find anything from ExifTool and Pillow metadata"
],
"metadata_basic_source": "null",
"ocr": [
"OCR did not detect AI",
0.0
],
"ml_model": [
"AI Generated",
90.2371538185235
],
"confidence": 90.2371538185235,
"heatmap_status": "ready",
"heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/...."
},
"preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}Interpretación de los Resultados
result: Puntuación de 1-100 que indica la probabilidad de que la imagen sea generada por IA. Puntuaciones más altas = mayor probabilidad de IA.final_result: La determinación general (ej: 'AI Generated', 'Real', 'Digitally Edited', 'AI Edited')confidence: La puntuación de confianza de la deteccióndetection_step: Indica la etapa en la que se completó la detección. 1 = solo metadatos devueltos, 2 = devuelve metadatos y OCR, 3 = devuelve metadatos, OCR y resultados del modelo ML (más completo)metadata: Información extraída de los metadatos de la imagen usando ExifTool y Pillowocr: Resultados del análisis de Reconocimiento Óptico de Caracteres para detección de marca de aguaml_model: Resultados del modelo de aprendizaje automático (clasificador basado en ConvNeXt)preview_url: URL de vista previa de la imagen (solo si generate_preview=true fue usado)heatmap_status: Estado de la generación del mapa de calor ('pending' o 'ready'). Nota: La generación del mapa de calor es asíncrona. Inicialmente, heatmap_status será 'pending' y heatmap_url puede estar ausente o nulo. Cuando esté listo, heatmap_status se convierte en 'ready' y heatmap_url se completa.heatmap_url: URL para la imagen del mapa de calor, disponible cuando heatmap_status es 'ready'. Solo disponible para imágenes con puntuación >= 20.
Nota Importante
La generación del mapa de calor es asíncrona. Inicialmente, heatmap_status será 'pending' y heatmap_url puede estar ausente o nulo. Cuando esté listo, heatmap_status se convierte en 'ready' y heatmap_url se completa. Los mapas de calor solo se generan para imágenes con puntuación >= 20.
Aquí, "result": 90.24 indica una alta probabilidad de que la imagen haya sido generada por IA. El "final_result": "AI Generated" proporciona una determinación clara, y "confidence": 90.24 indica alta confianza en este resultado. El campo "detection_step": 3 indica que se completó el análisis completo (metadatos, OCR y modelo ML). El "heatmap_status": "ready" y "heatmap_url" proporcionan acceso al mapa de calor visual que muestra las áreas detectadas como generadas por IA.
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-image.truthscan.com/check-user-creditsEjemplo de Solicitud
curl -X 'GET' \
'https://detect-image.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
Este endpoint le permite verificar el estado del servicio de detección de imagen IA.
GET https://detect-image.truthscan.com/healthEjemplo de Solicitud
curl -X 'GET' \
'https://detect-image.truthscan.com/health' \
-H 'accept: application/json'Ejemplo de Respuesta
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00Z"
}Una respuesta "healthy" indica que el servicio está funcionando normalmente.
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 imagen. |
| 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 imagen
Solución:
- Verifique sus créditos restantes usando /check-user-credits
- Compre créditos adicionales si es necesario
- Optimice el tamaño de las imágenes antes de cargar para consumir menos créditos
Problemas de Validación de Entrada
"Formato de archivo no soportado" (400)
Causa: Formato de imagen no soportado o inválido enviado
Solución:
- Verifique que el formato de imagen sea soportado (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
- Asegúrese de que el archivo no esté corrupto
- 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:
- Redimensione o comprima la imagen a menos de 10MB
- Verifique el tamaño del archivo antes de cargar
- Use formatos más eficientes como WebP cuando sea posible
Problemas de Procesamiento
"Tiempo de espera de la solicitud" (WebSocket)
Causa: El procesamiento de la imagen tardó demasiado tiempo
Solución:
- Intente con una imagen más pequeña o menos compleja
- Verifique si el servicio está experimentando alta carga
- Vuelva a intentar la solicitud
Estado del Documento "fallido"
Causa: El procesamiento falló por varias razones
Solución:
- Verifique si la imagen cumple con los requisitos mínimos (1KB - 10MB)
- Verifique que la imagen esté en un formato soportado
- Verifique que la carga se completó exitosamente antes de enviar para detección
- Contacte al soporte si el problema persiste
Problemas de Carga
"Fallo en la carga de la imagen" (403/400)
Causa: URL pre-firmada inválida o expirada, o problemas con el servidor de almacenamiento
Solución:
- Asegúrese de usar la URL pre-firmada inmediatamente después de recibirla (puede expirar)
- Verifique que el encabezado Content-Type sea correcto para el formato de imagen
- Elimine espacios del nombre del archivo antes de cargar
- 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:
- Elimine todos los espacios del nombre del archivo antes de solicitar la URL pre-firmada
- Use solo caracteres alfanuméricos, guiones y guiones bajos en el nombre del archivo
- 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.
Preguntas Frecuentes sobre la API
Encuentre respuestas a las preguntas más comunes sobre nuestra API de detección de imagen IA.