본문으로 건너뛰기

Hermes AI API Agent Skill

Hermes AI API로 이미지, 동영상, 음악, 가사를 생성하는 법을 에이전트에 알려 줍니다: 모델 선택, 작업 제출, 상태 확인, 결과 다운로드.

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 서버

Install

이 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_key

Claude

Download hermes-ai-api.zip. Claude에서 설정 → 기능 → Skills를 열고 zip을 업로드하세요. Claude 앱은 환경 변수를 읽을 수 없으므로 MCP 커넥터를 권장합니다. 키 없이 로그인됩니다.

기타 에이전트

Skill이나 지침을 읽는 에이전트라면 SKILL.md를 바로 사용할 수 있습니다. 이 URL을 알려 주거나 파일을 지침에 복사하세요.

URL
https://api.hermes-ai.net/skills/hermes-ai-api/SKILL.md

SKILL.md

The exact file your agent loads. It is generated from the live API contract, so statuses and error codes stay current.

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

Files

URL유형Use
/skills/hermes-ai-api/SKILL.mdtext/markdownThe skill itself, to read or point an agent at
/skills/hermes-ai-api.zipapplication/zipA hermes-ai-api/ folder with SKILL.md, ready to unzip