Inicio rápido

Esta guía muestra el flujo de la API v2: subir un fichero, crear una ejecución y consultar sus resultados.

Define la URL base una sola vez. El esquema OpenAPI actual usa /api/v2:

API_URL="https://veraquo.gradiant.org/api/v2"
API_KEY="{API_KEY}"

Subir un fichero

El campo multipart obligatorio se llama file. La respuesta 201 devuelve un objeto FileResponse con el identificador del fichero.

curl -X POST "$API_URL/files" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY" \
  -F 'file=@./ruta/al/fichero.webp'

Respuesta abreviada:

{
  "id": "{FILE_ID}",
  "filename": "fichero.webp",
  "url": "{FILE_URL}",
  "created_at": "2026-03-16T11:39:32Z",
  "status": "ready",
  "format": "image"
}

Crear una ejecución

Cuando el fichero esté disponible, crea una ejecución con file_id. Los workers son opcionales; si se omiten, la API selecciona los permitidos para el usuario.

curl -X POST "$API_URL/runs" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_id": "{FILE_ID}",
    "run_schemas": null,
    "workers": null
  }'

Respuesta 201:

{
  "id": "{RUN_ID}",
  "status": "queued",
  "created_at": "2026-03-16T11:40:00Z",
  "completed_at": null,
  "file_id": "{FILE_ID}"
}

Consultar el estado

La API v2 no tiene un endpoint /status separado. Consulta la ejecución con GET /runs/{run_id} hasta que su estado sea ready, ok, alert o error.

curl "$API_URL/runs/{RUN_ID}" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Los estados definidos por la API incluyen created, queued, processing, unprocessed, ready, error, alert y ok.

Obtener resultados

Cuando la ejecución haya terminado, consulta GET /runs/{run_id}/results:

curl "$API_URL/runs/{RUN_ID}/results" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Cada resultado puede incluir id, result, result_details, worker_name, result_file_urls, detail, created_at, started_at, completed_at, info, extra_details y run_id.

Para consultar los metadatos del fichero original usa GET /files/{file_id}. Para descargar un fichero usa GET /files/{file_id}/download.

Resumen

1. Subir el fichero con POST /files y guardar id.
2. Crear una ejecución con POST /runs usando ese file_id y guardar id.
3. Consultar GET /runs/{run_id} hasta que termine.
4. Recuperar los resultados con GET /runs/{run_id}/results.