Inicio rápido

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

Define la URL base una sola vez:

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"
}

Antes de crear una ejecución, comprueba que el fichero esté listo:

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

Solo crea la ejecución cuando status sea ready. Si es pending, vuelve a consultar el fichero más tarde. Si es error o deleted, no lo uses para crear una ejecución.

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 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.

Paginación y filtros

Los listados aceptan limit y offset. También puedes ordenar los resultados con order_by y order:

curl "$API_URL/files?limit=20&offset=0&order_by=created_at&order=desc" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

curl "$API_URL/runs/{RUN_ID}/results?limit=20&offset=0&order_by=created_at&order=desc" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Usa el campo total de la respuesta para saber cuántos elementos existen y aumenta offset para obtener la página siguiente. Los filtros y resultados de una API Key siguen limitados a los recursos creados con esa clave.

Errores y respuestas

• 401 Unauthorized: falta la autenticación, el token o la API Key no son válidos, o se ha usado una API Key en una operación reservada al usuario.
• 403 Forbidden: las credenciales son válidas, pero no permiten acceder al recurso solicitado.
• 404 Not Found: el identificador no existe o el recurso no está disponible para esas credenciales.
• 422 Unprocessable Entity: la petición no cumple el esquema esperado. La respuesta incluye un array detail con la ubicación y descripción del error.
• 204 No Content: la operación se completó correctamente y no devuelve cuerpo, por ejemplo al eliminar un recurso.

Los errores de ejecución se indican además mediante el campo status y pueden incluir información adicional en detail.

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.