# RPT AI Music: guide for AI agents

Make instrumental music or a sound effect from a text description. Uses an API key (token) created in the
Developers area of https://video.ai-agent.io.vn. The same key works on both hosts below.

- REST base: `https://music.ai-agent.io.vn/v1` (or `https://video.ai-agent.io.vn/v1`)
- MCP endpoint: `https://video.ai-agent.io.vn/api/v1/agent/mcp`
- Full contract: `https://video.ai-agent.io.vn/v1/openapi.json`

## Rules

1. Send the key as `Authorization: Bearer <key>`. Never put it in a URL, a log or a reply to the user.
2. The key must be in `execute` mode and the `live` environment. Check with `GET /v1/me`.
3. Generating costs money. Quote first, tell the human the price (`estimated_micros`, USD millionths), and generate
   only after the human agrees or has given a budget.
4. Every `POST` needs an `Idempotency-Key` header (8 to 200 printable characters, a UUID is fine). Reuse the same
   value only to retry the identical request.
5. Do not loop on a failing step. Read the error `code`; retry only when `retryable` is true.

## REST flow

1. `POST /v1/media-tasks/quotes` with JSON `{"kind": "music", "prompt": "...", "duration_seconds": 30}`.
   - `kind`: `music` or `sfx`. `prompt`: 1 to 1000 characters. `duration_seconds`: 10 to 60.
   - Answer (201): the task, with `id`, `state: "QUOTED"`, `estimated_micros`, `currency`.
2. `POST /v1/media-tasks/{id}/generate` (no body).
3. `GET /v1/media-tasks/{id}` every 2 seconds until `state` is `READY` or `FAILED` (stop after 10 minutes).
4. `GET /v1/media-tasks/{id}/file` with the same Bearer header returns the audio file (usually MP3).

Other calls: `GET /v1/media-tasks?kind=music&limit=20` lists earlier tasks; `POST /v1/media-tasks/{id}/cancel` cancels.

## MCP flow

`initialize` with the Bearer key, then: `get_workspace` (read `workspace_id`) → `quote_media_task(workspace_id, kind,
prompt, duration_seconds, request_key)` → `generate_media_task(workspace_id, task_id, request_key)` →
`get_media_task(workspace_id, task_id)`. `request_key` is a fresh UUIDv4 per write.

## Errors

Body: `{code, message, retryable, request_id}`. Common codes:

| Code | Meaning | What to do |
|---|---|---|
| `UNAUTHENTICATED` (401) | Key missing, wrong or expired | Ask the human for a new key |
| `MODE_FORBIDS_TOOL` (403) | Key is not in execute mode | Ask for an execute-mode key |
| `SANDBOX_NO_SPEND` (403) | Sandbox key | Ask for a live key |
| `TASK_MODEL_UNAVAILABLE` (409) | Music is not enabled for the workspace | Tell the human |
| `MEDIA_NOT_READY` (409) | File asked for before `READY` | Keep polling |
| `V1_IDEMPOTENCY_KEY_REQUIRED` (400) | Missing header on a write | Add `Idempotency-Key` |
| 429 | Rate limit | Wait `Retry-After` seconds |

## Writing the description

The result is instrumental: no singing, no lyrics. A good description names:

- the use (birthday video, product intro, calm background);
- two or three instruments (acoustic guitar, piano, bamboo flute, strings, drums);
- mood and tempo (warm, lively, solemn; slow, medium, fast; a BPM number is fine);
- texture words (warm, crisp, airy, punchy, lush);
- how it changes over time (soft opening, rise in the middle, gentle ending).

Do not name artists, bands or existing songs; describe the style instead. Do not mix styles that clash. Less detail
gives the model more freedom; more detail stays closer to the brief. If the result misses, change one or two words and
quote again.

Example: `Warm instrumental for a birthday video. Acoustic guitar and piano, medium tempo around 96 BPM, gently happy
and bright. Soft opening, fuller in the middle, settles softly at the end.`

Prompt advice follows the open-source ACE-Step prompt guide (MIT licence).