API de detección de imágenes con IA

1. Obtener una URL de carga preautorizada

Empiece solicitando una URL preautorizada a la API. Esta URL permite subir el archivo de imagen de forma segura al servidor de almacenamiento.

En archivos PDF solo se detectará la primera imagen (flujo de un solo archivo).

Use un nombre de archivo .zip en este endpoint cuando vaya a enviar un ZIP mediante carga masiva.

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

Ejemplo 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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id es un UUID nuevo generado para esta solicitud de carga (para correlación y registro). El id que use para /detect o /bulk-upload se asigna al enviar esos endpoints salvo que pase un id opcional en /detect.

2. Subir la imagen

Use la presigned_url proporcionada para subir la imagen mediante una solicitud PUT. Asegúrese de establecer el Content-Type correcto según el formato de la imagen.

Ejemplo de solicitud

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Ejemplos adicionales de carga (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

Asegúrese de que el formato del archivo se mantenga coherente durante la subida. Una subida correcta devuelve HTTP 200.

3. Enviar la imagen para la detección con IA

Tras la subida, envíe la imagen para la detección con IA referenciando el file_path del paso anterior. En cargas PDF solo se analizará o detectará la primera imagen.

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

Ejemplo 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": true
}'

FILE_PATH es la ruta devuelta en el paso de la URL preautorizada (p. ej. uploads/...). Construya la URL completa con su host de almacenamiento como en el ejemplo.

Ejemplo de solicitud (mapa de calor habilitado, predeterminado)

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-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": true,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Ejemplo de solicitud (mapa de calor deshabilitado)

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-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Solicitud no válida (422)

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-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_heatmap_overlayed": true
}'

Ejemplo de respuesta

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

La respuesta incluye un id de imagen único para seguir el estado de la detección.

Respuestas HTTP

1. El resultado inicial puede estar listo antes que el análisis

La detección principal (result, final_result, confidence) puede completarse mientras analysis_results_status sigue en pending.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

2. Siga consultando

Llame a /query con el mismo id hasta que analysis_results_status deje de ser pending.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Análisis completado

Cuando analysis_results_status es ready, analysis_results incluye agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns y recommendations.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Cuando el análisis no está disponible

Si analysis_results_status es skipped, failed o está ausente, o generate_analysis_details era false, considere la detección principal como definitiva.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Respuestas HTTP

Misma regla que /detect: cualquier 2xx con id, status y expected_count (si está presente) es éxito.

"User verification failed" (403)

Causa: Clave de API no válida o caducada

Solución:

1. Compruebe que la clave de API sea correcta
2. Verifique que la clave esté activa en su cuenta
3. Pruebe a regenerar la clave de API

"Not enough credits" (403)

Causa: Créditos insuficientes para el procesamiento de imágenes

Solución:

1. Consulte los créditos restantes con /check-user-credits
2. Compre créditos adicionales si es necesario

"Input URL cannot be empty" (400)

Causa: URL vacía o no válida enviada

Solución:

1. Asegúrese de que la entrada url no esté vacía
2. Elimine espacios iniciales o finales en los nombres de imagen
3. Compruebe que la codificación de URL sea correcta

"Input email is empty" (400)

Causa: Falta el correo para el procesamiento por URL

Solución:

1. Proporcione un correo electrónico válido al enviar URLs
2. Compruebe el formato del correo

"Unsupported image type" (400)

Causa: Formato de archivo no admitido

Solución:

1. Convierta a un formato admitido (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Compruebe que la extensión del archivo sea correcta

"File size is too small" (400)

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

Solución:

1. Use un archivo de imagen mayor (mínimo 1 KB)
2. Compruebe si la imagen se corrompió durante la subida

"File size exceeds limit" (400)

Causa: El archivo de imagen es demasiado grande

Solución:

1. Comprima o redimensione la imagen; el máximo depende del despliegue (el mensaje de error de la API indica el límite en MB)
2. Pruebe con otro formato de imagen

"Invalid file type" (400)

Causa: Falló la validación del tipo de archivo

Solución:

1. Asegúrese de que el archivo sea un formato de imagen válido
2. Compruebe que el archivo no esté corrupto
3. Verifique que el tipo MIME coincida con la extensión

Estado de imagen "failed"

Causa: El procesamiento falló por diversos motivos

Solución:

1. Verifique que la URL tenga un formato admitido
2. Compruebe que el archivo de imagen sea válido y no esté corrupto
3. Asegúrese de que la imagen cumpla los requisitos de tamaño
4. Contacte con soporte si el problema continúa

"User not found"

Causa: Id de usuario no válido

Solución:

1. Verifique que el id de usuario sea correcto
2. Asegúrese de que la cuenta de usuario esté activa
3. Vuelva a autenticarse si es necesario

"File metadata could not be fetched" (500)

Causa: No se pudo acceder al archivo subido

Solución:

1. Verifique que el archivo se subió correctamente
2. Compruebe que la URL del archivo sea accesible
3. Intente volver a subir el archivo

"Image upload failed" (403/400)

Causa: URL preautorizada no válida o caducada, o problemas con el servidor de almacenamiento

Solución:

1. Use la URL preautorizada en cuanto la reciba
2. Verifique que Content-Type coincida con el formato del archivo
3. Elimine espacios del nombre de archivo antes de subir
4. Genere una nueva URL preautorizada si hace falta

"Invalid pre-signed URL" (400)

Causa: Nombre de archivo con espacios o URL preautorizada caducada o corrupta

Solución:

1. Elimine espacios del nombre de archivo antes de solicitar la URL preautorizada
2. Use caracteres alfanuméricos, guiones y guiones bajos
3. Genere una nueva URL preautorizada si hace falta

"URL must point to a ZIP file" (400)

Causa: La URL proporcionada a /bulk-upload no apunta a un archivo ZIP

Solución:

1. Use get-presigned-url?file_name=images.zip (u otro nombre .zip)
2. Suba un ZIP válido a la URL preautorizada
3. Asegúrese de que la solicitud bulk-upload apunte con url a ese ZIP subido

"ZIP file too large" (400)

Causa: El ZIP supera el tamaño máximo (100 MB)

Solución:

1. Reduzca el número de imágenes o comprímalas
2. Divida en varias cargas masivas

"Too many files" (400)

Causa: El ZIP contiene más de 50 imágenes válidas

Solución:

1. Reduzca a 50 imágenes o menos por ZIP
2. Divida en varias cargas masivas

"No valid images found in ZIP" (400)

Causa: Todos los archivos del ZIP se omitieron (formato no admitido, demasiado pequeños, ruta no válida, etc.)

Solución:

1. Use formatos admitidos (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. El PDF no está admitido en masivo
3. Cada imagen debe tener al menos 1 KB y como máximo 10 MB
4. Evite archivos ocultos (nombres que empiezan por .) y path traversal (..)

"Document is not a bulk upload (image-zip) result" (400)

Causa: El id no corresponde a ese tipo de carga (imagen única frente a lote ZIP)

Solución:

1. Use el id de /detect para envíos de una sola imagen
2. Use el id de /bulk-upload para envíos ZIP