Hermes AI API Agent Skill
教智能体用 Hermes AI API 生成图片、视频、音乐和歌词:选择模型、提交任务、轮询并下载结果。
Skill 能做什么
- 查找模型并读取其输入字段和价格
- 上传本地文件,并用幂等键提交任务
- 轮询直到任务完成,并下载全部结果
- 查询额度,并解释任务状态和错误码
连接了 MCP 服务器时,Skill 会让智能体改用 MCP 工具而不是 REST API。 MCP 服务器
安装
该 Skill 通过 API 密钥使用 REST API。请创建密钥,并在智能体运行的环境中设置为 HERMES_API_KEY。
Claude Code
安装到 ~/.claude/skills 可用于所有项目,或安装到项目的 .claude/skills 目录。请求匹配时 Claude Code 会自动加载。
terminal
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
下载 hermes-ai-api.zip。 在 Claude 中打开“设置 → 功能 → Skills”并上传该 zip。 Claude 应用无法读取你的环境变量,因此建议在其中使用 MCP 连接器,无需密钥即可登录。
其他智能体
任何能读取 Skill 或指令的智能体都可以直接使用 SKILL.md。把这个 URL 提供给它,或将文件内容复制到它的指令中。
URL
https://api.hermes-ai.net/skills/hermes-ai-api/SKILL.mdSKILL.md
这就是智能体加载的文件。它根据当前 API 约定生成,任务状态和错误码始终是最新的。
hermes-ai-api/SKILL.md
---
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
文件
| URL | 类型 | 用途 |
|---|---|---|
| /skills/hermes-ai-api/SKILL.md | text/markdown | Skill 本身,可直接阅读或提供给智能体 |
| /skills/hermes-ai-api.zip | application/zip | 含 SKILL.md 的 hermes-ai-api/ 文件夹,可直接解压 |