Hermes AI API Agent Skill
Teaches an agent to generate images, videos, music and lyrics with the Hermes AI API: pick a model, submit a task, poll it and download the result.
What the skill does
- Find a model and read its input fields and price
- Upload local files and submit tasks with an idempotency key
- Poll until a task finishes and download every result
- Check credits and explain task statuses and error codes
When the MCP server is connected, the skill tells the agent to use its tools instead of the REST API. MCP server
Install
The skill uses the REST API with an API key. Create a key, then set it as HERMES_API_KEY where your agent runs.
Claude Code
Install it for all projects in ~/.claude/skills, or in a project's .claude/skills folder. Claude Code loads it automatically when a request matches.
mkdir -p ~/.claude/skills
curl -L https://api.hermes-ai.net/skills/hermes-ai-api.zip -o /tmp/hermes-ai-api.zip
unzip -o /tmp/hermes-ai-api.zip -d ~/.claude/skills
export HERMES_API_KEY=your_api_keyClaude
Download hermes-ai-api.zip. In Claude, open Settings → Capabilities → Skills and upload the zip. Claude apps can't read your environment, so prefer the MCP connector there; it signs in without a key.
Other agents
Any agent that reads skills or instructions can use the SKILL.md directly. Point it at this URL or copy the file into its instructions.
https://api.hermes-ai.net/skills/hermes-ai-api/SKILL.mdSKILL.md
The exact file your agent loads. It is generated from the live API contract, so statuses and error codes stay current.
---
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 | `EXPORT_RATE_LIMITED` | Too many CSV exports this minute. Honor Retry-After. |
| 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
Files
| URL | Type | Use |
|---|---|---|
| /skills/hermes-ai-api/SKILL.md | text/markdown | The skill itself, to read or point an agent at |
| /skills/hermes-ai-api.zip | application/zip | A hermes-ai-api/ folder with SKILL.md, ready to unzip |