Tareas y resultados

Envía tareas asíncronas de forma segura con idempotencia, sube archivos, consulta el estado y descarga resultados.

Enviar una tarea (asíncrona)

No hay llamada síncrona. POST /api/v1/jobs valida la entrada, reserva el precio de tus créditos y responde de inmediato: 202 para una tarea nueva, 200 cuando un reintento idempotente coincide con uno anterior.

Encabezado	Valor	Notas
`Authorization`	`Bearer <API key>`	O envía la clave en x-api-key.
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	Obligatorio. Reutilízalo solo para reintentar la misma solicitud.

Campo	Tipo	Obligatorio	Notas
`model`	`string`	obligatorio	Slug del modelo en el catálogo.
`input`	`object`	obligatorio	Campos del esquema de entrada del modelo.
`expectedPriceMicros`	`integer`	opcional	Precio que mostraste al usuario. Si no coincide, se devuelve 409 PRICE_CHANGED antes de cualquier cargo.

Reintenta con seguridad

Conserva la misma Idempotency-Key y el mismo cuerpo al reintentar tras un fallo de red. Usa una clave nueva si cambia la entrada. Reutilizar una clave con una entrada distinta devuelve 409 IDEMPOTENCY_CONFLICT.

Subir multimedia

Los campos de imagen y vídeo aceptan una URL HTTPS pública o una referencia media:<uuid>. Sube primero los archivos locales:

POST /api/v1/media

curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
# → { "reference": "media:<uuid>", ... }  Use the reference in an image or video field.

Obtener resultados de la tarea

Consulta GET /api/v1/jobs/{id} cada pocos segundos y detente en un estado final. No reenvíes automáticamente una tarea reconciliation_required.

Estado	Final	Significado
`queued`	no	Aceptada y a la espera de un trabajador.
`submitting`	no	Enviándose al proveedor del modelo.
`running`	no	El modelo está generando.
`succeeded`	sí	Terminada. Los resultados están en assets.
`failed`	sí	Terminada sin resultado. La reserva se libera.
`reconciliation_required`	sí	The result is being verified. Keep the task ID and do not resubmit automatically.

Campo	Tipo	Notas
`id`	`string`	ID de tarea de Hermes AI. Úsalo para consultar.
`model`	`string`	Slug del modelo.
`status`	`string`	Consulta los estados de la tarea.
`errorCode`	`string \| null`	Se establece cuando una tarea falla o requiere revisión.
`priceMicros`	`integer`	Cotización fijada al aceptarla, en micro-unidades de USD.
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	Marcas de tiempo ISO 8601.
`assets[]`	`array`	{ id, type, url?, text? }. url es un enlace /api/v1/results/<uuid> del mismo origen.
`replayed`	`boolean`	Solo al enviar. true cuando coincide un reintento idempotente.

Los recursos del resultado contienen texto o una URL /api/v1/results/<uuid> del mismo origen. Descarga los archivos con las mismas credenciales (permiso media:read). GET /api/v1/jobs lista tus últimas 100 tareas.