Inicio rápido

Esta sección muestra el flujo básico para utilizar la API: desde la subida de un fichero hasta la obtención de los resultados del procesamiento.

El flujo general consta de cuatro pasos:

1. Subir o enviar el fichero a procesar
2. Obtener el identificador de la tarea
3. Consultar el estado del procesamiento
4. Recuperar los resultados

Subida de fichero

En primer lugar es necesario subir a la plataforma el fichero que se quiere analizar.

Para ello se debe realizar una petición autenticada a la API incluyendo la API Key en la cabecera.

Ejemplo de petición:

curl -X POST 'https://fair-dev.gradiant.org/api/v1/files' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=...'

Esta petición devolverá un identificador único para el fichero. Este se utiliza para iniciar cualquier otra operación sobre el fichero.

{
  "file_ids": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ]
}

Enviar un fichero para procesar

Para analizar el documento, indicamos el ID del fichero en el endpoint correspondiente:

Ejemplo con curl:

curl -X 'POST' \
  'https://fair-dev.gradiant.org/api/v1/runs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY} \
  -H 'Content-Type: application/json' \
  -d '{
  "run_type": "detection",
  "file_ids": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ],
  "strength": 0,
  "algorithm": "string",
  "lang": "string",
  "context": "string",
  "threshold": 0,
  "top_n": 0,
  "exact_duplicated": true
}'

Si la petición es correcta, la API responderá con un JSON similar a:

{
  "success_queued_files": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ],
  "error_queued_files": [],
  "run_ids": [
    "40fa5bb8-37b7-45d1-9647-14233e490c5f"
  ],
  "details": [
    "file SDXL_1261.webp ok"
  ]
}

El campo run_ids contiene los identificadores únicos de las tareas y serán necesarios para consultar su estado y resultados.

Consultar el estado de la tarea

El procesamiento puede no ser inmediato, especialmente en el caso de vídeos o audios largos. Para comprobar el estado se utiliza el siguiente endpoint, incluyendo el run_id correspondiente:

curl -X 'GET' \
  'https://fair-dev.gradiant.org/api/v1/runs/40fa5bb8-37b7-45d1-9647-14233e490c5f/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}"

Respuesta de ejemplo mientras se está procesando:

{
  "status": "processing"
}

Cuando el estado cambie a:

{
  "status": "ok",
  "result_ids": [
    "2df5032e-9506-47ea-a0fe-dbd642faa5ee"
  ]
}

significa que los resultados ya están disponibles.

Obtener los resultados

Una vez completada la tarea, los resultados pueden consultarse pidiendo la información disponible sobre el fichero con el correspondiente file_id:

curl -X 'GET' \
  'https://fair-dev.gradiant.org/api/v1/files/ac38014e-7b31-470d-b013-dc5318055adc' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}"

Respuesta de ejemplo:

{
  "id": "ac38014e-7b31-470d-b013-dc5318055adc",
  "type": "image/webp",
  "format": "image",
  "filename": "SDXL_1261.webp",
  "state": "ready",
  "detection_state": {
    "state": "alert",
    "detail": null,
    "remaining_time": null
  },
  "tracing_state": {
    "state": null,
    "detail": null,
    "remaining_time": null
  },
  "protection_state": {
    "state": null,
    "detail": null,
    "remaining_time": null
  },
  "created": "2026-03-05T15:32:13",
  "duration": null,
  "file_url": "ac38014e-7b31-470d-b013-dc5318055adc.webp",
  "detection_results": {
    "run_id": "40fa5bb8-37b7-45d1-9647-14233e490c5f",
    "result": "alert",
    "start_date": "2026-03-11T07:58:59",
    "end_date": "2026-03-11T07:59:31",
    "extra_details": null,
    "details": [
      {
        "result_id": "c0065e39-5c63-4c65-a764-ddc24a77e1eb",
        "file_url": "ac38014e-7b31-470d-b013-dc5318055adc.webp",
        "name": "Synthetic",
        "result": "alert",
        "detail": "Synthetic: synthetic detection",
        "score": 0.7395417094230652,
        "decision": "Stable Diffusion XL",
        "color": "#FF0000",
        "info": "Detect synthetic images",
        "extra_details": null
      }
    ]
  },
  "tracing_results": null,
  "protection_results": null
}

El contenido exacto dependerá del tipo de fichero procesado y del modelo aplicado.

Resumen del flujo completo

1. Se envía un fichero mediante una petición autenticada.
2. La API devuelve un file_id.
3. Se inicia una operción de análisis sobre ese fichero, indicando su file_id.
4. La API devuelve un run_id.
5. Se consulta periódicamente el estado mediante ese run_id.
6. Cuando el estado es OK o Alert, se recuperan los resultados.

Este modelo asíncrono permite procesar ficheros de distinto tamaño sin bloquear la API y garantiza escalabilidad incluso bajo carga elevada.