---
name: hermes-ai-api
description: Generate images, videos, music and lyrics with the Hermes AI API (https://api.hermes-ai.net). Use when the user asks to create or edit an image, make a video, compose a song or lyrics with a hosted AI model, or check their Hermes AI API credits and tasks.
---

# Hermes AI API

Hermes AI API runs hosted image, video, music and text models through one asynchronous job API.
Every call is a task: submit it, poll it, download the result. Tasks are paid from the user's
prepaid credits, and only successful tasks are charged.

## Setup

- If the `hermes-ai-api` MCP server is connected (https://api.hermes-ai.net/mcp), prefer its tools: `search_models`,
  `get_model`, `create_task`, `wait_for_task`, `get_task`, `list_tasks`, `get_balance`.
- Otherwise use the REST API below with the key in `$HERMES_API_KEY`. If it is not set, ask the
  user to create one at https://api.hermes-ai.net/dashboard/api-keys and export it. Never print the key or
  write it into files.

## Workflow

1. **Pick a model.** `GET https://api.hermes-ai.net/api/v1/models` lists every model with its `slug`,
   `category` and input `fields`. Current prices: `GET https://api.hermes-ai.net/api/v1/prices`.
   A model without a price, or with `enabled: false`, cannot run.
2. **Build the input** from that model's `fields` only. Respect `required`, `options`,
   `default`, `min`/`max` and length limits. Unknown fields are rejected.
   Media fields take a public HTTPS URL, or upload a local file first and pass the returned
   `reference` (`media:<uuid>`):
   `curl -X POST https://api.hermes-ai.net/api/v1/media -H "Authorization: Bearer $HERMES_API_KEY" -H "Content-Type: image/png" --data-binary @photo.png`
3. **Submit** with a fresh Idempotency-Key:

```bash
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "<slug>", "input": { ... }}'
```

   The response (202) contains the task `id`. After a network error, retry with the same
   Idempotency-Key and body; it never charges twice.
4. **Poll** `GET https://api.hermes-ai.net/api/v1/jobs/<id>` every 4–5 seconds until the status is terminal.
5. **Download** each `assets[].url` with the same Authorization header and save it with an
   extension that matches `assets[].type`. Text results are in `assets[].text`.

## Task statuses

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

Never resubmit a `reconciliation_required` task automatically; report its ID to the user.

## Errors

Error bodies are `{ "code": "...", "error": "..." }`. Branch on `code`.

| HTTP | Code | Meaning |
| --- | --- | --- |
| 401 | `AUTH_REQUIRED` | Missing or invalid API key or session. |
| 403 | `INSUFFICIENT_SCOPE` | The API key lacks the scope this endpoint needs. |
| 403 | `PERMISSION_DENIED` | This credential cannot perform the operation. |
| 429 | `API_KEY_RATE_LIMITED` | The API key's rate limit was reached. Honor Retry-After. |
| 429 | `API_KEY_USAGE_EXCEEDED` | The API key reached its usage limit. Create a new key. |
| 400 | `INVALID_REQUEST` | The body is not a JSON object or a required value is missing. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Idempotency-Key must be 1–128 printable ASCII characters. |
| 400 | `INVALID_MODEL_INPUT` | input does not match the model schema (unknown field, missing required field, or invalid value). |
| 400 / 413 | `INPUT_TOO_LARGE` | The request body is larger than 256 KB. Upload media first and send a media reference. |
| 404 | `REQUEST_NOT_FOUND` | No chat request with this ID belongs to your account. |
| 404 | `MODEL_NOT_FOUND` | No model has this slug. |
| 404 | `JOB_NOT_FOUND` | No task with this ID belongs to your account. |
| 409 | `IDEMPOTENCY_CONFLICT` | This Idempotency-Key was used with different input. Use a new key for a new request. |
| 409 | `PRICE_CHANGED` | The price differs from expectedPriceMicros. Fetch the price and confirm again. |
| 409 | `MODEL_PRICE_UNAVAILABLE` | No price is configured for this model yet, so it cannot run. |
| 409 | `PAYMENT_REVIEW_REQUIRED` | A refund left an uncovered balance. Contact support or cover the balance before submitting tasks. |
| 409 | `INSUFFICIENT_CREDITS` | Available credits do not cover the task price. |
| 429 | `RATE_LIMITED` | Too many task submissions per minute. Retry later. |
| 429 | `CONCURRENCY_LIMITED` | Too many unfinished tasks. Wait for one to finish. |
| 503 | `EXECUTION_UNAVAILABLE` | Execution is not configured for this model right now. |
| 429 | `UPSTREAM_RATE_LIMITED` | The model provider is rate limiting chat requests. Retry with backoff; nothing was charged. |
| 502 | `UPSTREAM_ERROR` | The model provider failed the chat request. Nothing was charged; retry later. |
| 503 | `PLATFORM_BUDGET_EXCEEDED` | This model is temporarily unavailable. Try again later. |
| 503 | `EXECUTION_TEMPORARILY_UNAVAILABLE` | Execution is temporarily unavailable. Retry with the same Idempotency-Key. |
| 503 | `AUTH_UNAVAILABLE` | Authentication is temporarily unavailable. Retry later. |
| 503 | `API_UNAVAILABLE` | The API is temporarily unavailable. Retry later. |

## Guidance

- Tell the user the model and price before running an expensive task, and check the balance
  with `GET https://api.hermes-ai.net/api/v1/usage` when unsure.
- Video and music tasks can take minutes; keep polling and report progress.
- Full reference: https://api.hermes-ai.net/docs · Models: https://api.hermes-ai.net/models · OpenAPI: https://api.hermes-ai.net/api/openapi.json