Aller au contenu

Hermes AI API Agent Skill

Apprend à un agent à générer images, vidéos, musique et paroles avec Hermes AI API : choisir un modèle, soumettre et suivre une tâche, télécharger le résultat.

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. Serveur MCP

Install

Le skill utilise l’API REST avec une clé d’API. Créez une clé, puis définissez-la comme HERMES_API_KEY là où votre agent s’exécute.

Claude Code

Installez-le pour tous les projets dans ~/.claude/skills, ou dans le dossier .claude/skills d’un projet. Claude Code le charge automatiquement quand une demande correspond.

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. Dans Claude, ouvrez Paramètres → Fonctionnalités → Skills et importez le zip. Les applications Claude ne lisent pas votre environnement : préférez-y le connecteur MCP, qui se connecte sans clé.

Autres agents

Tout agent qui lit des skills ou des instructions peut utiliser le SKILL.md directement. Indiquez-lui cette URL ou copiez le fichier dans ses instructions.

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

URLTypeUse
/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