Tasks and results

Submit asynchronous tasks safely with idempotency, upload media, poll for status and download results.

Submit a task (async)

There is no synchronous call. POST /api/v1/jobs validates the input, reserves the price from your credits and returns immediately: 202 for a new task, 200 when an idempotent retry matches an earlier one.

Header	Value	Notes
`Authorization`	`Bearer <API key>`	Or send the key in x-api-key.
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	Required. Reuse it only to retry the identical request.

Field	Type	Required	Notes
`model`	`string`	required	Model slug from the catalog.
`input`	`object`	required	Fields from the model's input schema.
`expectedPriceMicros`	`integer`	optional	Price you showed the user. A mismatch returns 409 PRICE_CHANGED before any charge.

Retry safely

Keep the same Idempotency-Key and body when retrying after a network failure. Use a new key for changed input. Reusing a key with changed input returns 409 IDEMPOTENCY_CONFLICT.

Upload media

Image and video fields take a public HTTPS URL or a media:<uuid> reference. Upload local files first:

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.

Get task results

Poll GET /api/v1/jobs/{id} every few seconds and stop at a terminal status. Do not resubmit a reconciliation_required task automatically.

Status	Terminal	Meaning
`queued`	no	Accepted and waiting for a worker.
`submitting`	no	Being sent to the model provider.
`running`	no	The model is generating.
`succeeded`	yes	Finished. Results are in assets.
`failed`	yes	Finished without a result. The hold is released.
`reconciliation_required`	yes	The result is being verified. Keep the task ID and do not resubmit automatically.

Field	Type	Notes
`id`	`string`	Hermes AI task ID. Use it to poll.
`model`	`string`	Model slug.
`status`	`string`	See task statuses.
`errorCode`	`string \| null`	Set when a task fails or needs review.
`priceMicros`	`integer`	Quote fixed at admission, USD micro-units.
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 timestamps.
`assets[]`	`array`	{ id, type, url?, text? }. url is a same-origin /api/v1/results/<uuid> link.
`replayed`	`boolean`	Submit only. true when an idempotent retry matched.

Result assets contain text or a same-origin /api/v1/results/<uuid> URL. Download files with the same credentials (scope media:read). GET /api/v1/jobs lists your latest 100 tasks.