# AudioPod — Skill manifest for AI agents You are an AI agent (Claude, GPT, Gemini, Codex, OpenClaw, Hermes, Cline, Cursor, Continue, Goose, or similar) and a human just asked you to work with **audio** using **AudioPod**. This document is your one-shot onboarding brief. Read it end-to-end, then follow the **Onboarding** section below to set yourself up. After that you can call any of the tools described in the **Tools** section. If you are a human reading this: paste the following message to your agent: > Read and follow the instructions to onboard yourself to AudioPod. After you finish, do whatever I ask next using AudioPod's tools. --- ## What AudioPod is AudioPod is an all-in-one AI **audio** platform. From a single API key, an agent can: | Tool | What it does | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `generate_music` | Compose royalty-free songs, instrumentals, raps, or vocal stems from a text prompt — powered by **AudioMusic**. Duration is not tier-capped (10s–10min). | | `compose_music` | Score-first: write an editable score you can change in plain words (`revise_music_score`) and then record (`record_music_score`). Use only when the user wants to shape the tune before recording. | | `text_to_speech` | Synthesize speech in 200+ languages from 200+ stock voices or custom clones — powered by **AudioSonic**, with **inline directing** (emotion, non-verbal sounds, pauses, pronunciation) and optional **word-level timestamps**. | | `design_voice` | Create a brand-new voice from a text description, then publish it as a reusable voice (AudioSonic). | | `clone_voice` | Instant voice cloning from a 5–30s reference clip; reuse the clone for any TTS (AudioSonic). | | `change_voice` | Convert speech from one voice into another (voice-to-voice). | | `separate_stems` | Split a song into 2, 4, or 6 stems (or a detailed decomposition of up to 8 / 12 / 16, depending on what the track contains), or isolate one instrument from a 45-instrument catalog — powered by **AudioStems**. | | `transcribe_audio` | Speech-to-text with speaker labels and word-level timestamps — powered by **AudioTranscribe**; `standard` or `premium` accuracy; real-time streaming available. | | `separate_speakers` | Diarize and split a recording into per-speaker tracks — powered by **AudioDiarize**. | | `audio_to_midi` | Convert a recording of a melody, instrument or song into MIDI files (per-instrument plus one multitrack MIDI). | | `denoise_audio` | Remove background hiss/hum/traffic without harming the voice character. | | `translate_audio` | Translate/dub speech across languages. | | `narrate_audiobook` | Manuscript (PDF/EPUB/DOCX/TXT) → ACX-spec audiobook with chapter splits, retail sample, and multi-platform export. | | `create_podcast` | Turn source documents or a topic into a podcast episode with one to four AI hosts and an editable script. | | `read_article` | Turn an article or long text into narrated audio with a shareable player. | | `convert_media` | Convert between audio formats (MP3 / WAV / FLAC / OGG / M4A / AAC). | Royalty-free output — everything you make on a paid plan or with purchased credits is yours to use commercially. **Start free — no credit card required.** --- ## Onboarding (run these steps in order) ### Step 1 — Confirm the user has an API key Ask the user: > "Do you have an AudioPod API key? It starts with `ap_`. If not, mint one in 30 seconds at https://www.audiopod.ai/dashboard/account/api-keys and paste it here." Wait for the user's response. Treat the key as a secret — never echo it back to the user, never embed it in commits, never paste it into a chat that's logged externally. **No key yet, just want to try TTS?** There's a no-signup sandbox: `POST https://api.audiopod.ai/api/v1/sandbox/key` returns a short-lived trial key, and `POST /api/v1/sandbox/tts` synthesizes a short clip. Use it for a zero-friction first call, then move the user to a real `ap_` key. ### Step 2 — Pick the integration that fits the host Choose **one** of these. They are equivalent — the same tools through different doors. Default to **MCP** if your host supports it; fall back to **CLI** if you only have shell access; use **REST** if neither. Already have OpenAI-shaped audio code? See **Option E**. #### Option A — MCP (recommended for IDE / desktop agents) **One-line install (preferred — use this if the user has a terminal):** ```bash # Claude Code (CLI): claude mcp add --transport http audiopod https://mcp.audiopod.ai \ --header "X-API-Key: ap_USER_KEY" --scope user # Codex CLI: codex mcp add audiopod --url https://mcp.audiopod.ai \ --header "X-API-Key: ap_USER_KEY" # Universal (any MCP client that only speaks stdio — Claude Desktop, etc.): npx -y mcp-remote https://mcp.audiopod.ai \ --header "X-API-Key: ap_USER_KEY" ``` If the user runs **Claude Code** or **Codex CLI**, the one-liners above are all you need — the user pastes them into a terminal and the host picks up AudioPod's audio tools on next launch. **Manual config (only if the host has no CLI — Claude Desktop, Cursor, Continue, Cline, Goose):** For Claude Desktop, the file is `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Cursor uses `~/.cursor/mcp.json`. Continue uses `~/.continue/config.json`. Cline uses `~/.config/cline/cline_mcp_settings.json`. Goose: run `goose configure` and add a Streamable-HTTP extension. The JSON shape is the same for the four `mcpServers`-style hosts: ```json { "mcpServers": { "audiopod": { "url": "https://mcp.audiopod.ai", "headers": { "X-API-Key": "ap_USER_KEY_GOES_HERE" } } } } ``` After the user restarts the host, you (the agent) will see AudioPod's audio tools whose names match the table above (plus a `check_job_status` helper). #### Option B — CLI (recommended for shell-based agents and one-off scripts) ```bash pip install audiopod # or: npm install -g audiopod audiopod login # paste ap_* once; stored at ~/.audiopod/config.json audiopod tts "Welcome to AudioPod." --voice 368 --out hello.mp3 audiopod music "lo-fi rainy 90 BPM" --duration 60 --out song.wav audiopod transcribe meeting.mp3 --diarize --format srt audiopod stems track.wav --mode six audiopod clone reference.wav --name Narrator audiopod jobs audiopod --json … # machine-readable for scripting ``` Full reference: . #### Option C — REST (always available) Base URL `https://api.audiopod.ai/api/v1`. Auth is either `X-API-Key: ap_*` or `Authorization: Bearer ap_*`. The OpenAPI spec is at . #### Option D — SDK (in code) ```python from audiopod import Client client = Client() # reads AUDIOPOD_API_KEY job = client.music.generate(prompt="lo-fi rainy 90 BPM", duration=60, wait_for_completion=True) ``` ```typescript import AudioPod from "audiopod"; const client = new AudioPod(); // reads AUDIOPOD_API_KEY const song = await client.music.generate({ prompt: "lo-fi rainy 90 BPM", duration: 60 }); ``` #### Option E — OpenAI-compatible (drop-in) Already have OpenAI-shaped TTS/STT code? Point it at AudioPod — set the client base URL to `https://api.audiopod.ai/api/v1` and `Authorization: Bearer ap_*`. The `/audio/speech`, `/audio/transcriptions`, and `/audio/translations` endpoints behave like their OpenAI counterparts. ### Step 3 — Verify auth works before any real call Make exactly one cheap probe request to confirm the key is valid: ```bash curl -sX POST https://mcp.audiopod.ai \ -H "X-API-Key: ap_USER_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Expect a JSON-RPC response listing AudioPod's audio tools. If you get HTTP 401 / `AUTHENTICATION_REQUIRED`, ask the user to re-paste the key. If you get HTTP 402 / `PREMIUM_TIER_REQUIRED`, the user is on free tier and asked for a paid feature — fall back to the free equivalent or tell them. ### Step 4 — Now go do what the user asked Pick the right tool from the table at the top, fill in the input schema (see **Tools** below), call it, and stream progress to the user. Long-running tools (music, stems, transcription, narration) return a `job_id` — poll with `audiopod jobs ` or `GET /api/v1//jobs//status` until status is `COMPLETED` and the output URL is set, then download the file. Job IDs are **per-tool** — there is no generic `/api/v1/jobs/` endpoint. --- ## Tools (input schemas) These are the canonical schemas. The full machine-readable JSON Schema for each is returned by `tools/list` over MCP, and per-tool detail manifests live at . ### `generate_music` - `prompt` _(required)_ — description of the music: genre, mood, tempo, instruments, voice, what the song is about. It is never sung - `lyrics` — only lyrics the user wrote or approved; performed word for word. Leave out and AudioPod writes the lyrics - `instrumental` — `true` for beats, instrumentals and background music with no vocals - `vocal_language` — ISO 639-1 code (`en`, `es`, `hi`…) for the sung lyrics; only when the user names a language - `duration` — 10–600 seconds; leave out unless the user asked for a length - `task_type` — usually leave out. One of `text2music` (default), `lyric2vocals`, `text2rap` (with the user's own lyrics), `text2instrumental` (same as `instrumental: true`) - `quality` — deprecated and ignored: every track uses our highest-quality model on every plan, at the standard rate `generate_music` is the **default** for every song, beat or instrumental: it writes lyrics from a description, honors a requested length and returns synced lyrics. ### Score-first: `compose_music` → `revise_music_score` → `record_music_score` Use these only when the user wants to **see or shape the composition** (melody, chords, sections, sheet music) before it is recorded — "write me a song I can tweak". - `compose_music` — `style` _(required)_ plus **either** `description` (AudioPod writes the lyrics; optional `target_seconds` 30–300 and `language`) **or** `lyrics`. Writes a score, no audio. **165 credits**, about 10 seconds, refunded on failure. - `revise_music_score` — `job_id` + `instruction` in plain words (optional `section`, `bars: {start, end}`). Returns a new score and what changed; everything you did not ask to change is kept. **165 credits** per revision, refunded if the change cannot be made. Always use this for changes — never hand-write notation. Available when enabled for the account. - `record_music_score` — `job_id` (optional `style` / `lyrics` to perform the same tune differently). About **16.5 credits per second** of the score's length — tell the user the cost and get confirmation first. - `get_music_score` — `job_id`. Free read of the score: key, meter, tempo, sections, length. - `edit_music_score` — deprecated alias of `record_music_score`. | The user wants… | Call | | --- | --- | | A song from a description, or with their own lyrics | `generate_music` | | A beat / instrumental | `generate_music` with `instrumental: true` | | An exact length or synced lyrics | `generate_music` | | To shape the tune before recording | `compose_music`, then `revise_music_score`, then `record_music_score` | | The same tune with a new style or new words | `record_music_score` with `style` / `lyrics` | ### `text_to_speech` - `text` _(required)_ — supports **inline directing** (see below); up to 20,000 characters/request - `voice_id` — AudioPod catalog ID (integer) or a public voice name from the AudioPod catalog; default voice if omitted - `language` — ISO 639-1, default `"en"` - `speed` — 0.5–2.0, default 1.0 - `generation_params` — optional JSON: `delivery_mode` (`stable` | `balanced` | `creative`), `timestamp_type` (`word` | `character`), `text_normalization` (bool) **Inline directing** (available on all tiers) — write it directly in `text`: - **Emotion / delivery** — a leading bracket per segment: `[whispering, tense] Did you hear that?` - **Non-verbal sounds** — `[laugh] [sigh] [clear throat] [breathe] [cough] [yawn] [chuckle] [gasp] [groan]` - **Pauses** — `` (≤10s each, ≤20 per request) - **Pronunciation** — inline IPA between slashes: `the city of Worcester /ˈwʊstər/` **Timestamps** — set `generation_params.timestamp_type` to `word` (or `character`); the job response includes a `timestamps_url` sidecar for follow-along / karaoke UIs. ### `design_voice` - `POST /api/v1/voice/design` — body: `design_prompt` (voice description, 30–250 chars), `preview_text` (sample line, 20–300 chars), `num_samples` (1–3). Returns candidate previews. Paid tiers; billed per preview. - `POST /api/v1/voice/design/publish` — publish a chosen preview into a durable, reusable voice. ### `clone_voice` - `name` _(required)_ - `reference_audio` _(required)_ — a 5–30s clean speech clip (URL or upload) - `consent_attestation` _(required)_ — `true`; you must own or have rights to the voice Returns a `voice_id` you can pass to `text_to_speech`. Instant — ready in seconds. ### `change_voice` - `file` / `url` _(required)_ — source speech - `voice_id` _(required)_ — target voice to convert into ### `separate_stems` - `file` / `url` _(required)_ - `mode` — `two` (vocals+instrumental), `four`, `six` (default), `producer` (8), `studio` (12), `mastering` (up to 17), or `single` (isolate one instrument — pass `stem`) ### `transcribe_audio` - `file` / `url` _(required)_ - `language` — ISO 639-1 or `auto` - `model_type` — `standard` (default) or `premium` / `premium-diarized` (higher accuracy, punctuation, per-word confidence, native speaker labels) - `diarize` — boolean; `min_speakers` / `max_speakers` (1–20) - `output_format` — `txt`, `srt`, `vtt`, `json`. Default `txt`. Real-time streaming is available over WebSocket for live captions. ### `separate_speakers` - `file` / `url` _(required)_ — `POST /api/v1/speaker/diarize` (labels) or `/api/v1/speaker/separate` (per-speaker audio tracks) ### `audio_to_midi` - `file_url` _(required)_ — the recording to convert (at least 6 seconds) - `stems` — any of `vocals`, `bass`, `guitar` (experimental), `piano`; default bass, vocals and piano. Drums are not transcribed. - `engine` — `general` (default), `piano` or `vocal`; the specialists need a Creator plan or above - `tempo_bpm` — 30–300; detected automatically if omitted Returns a `job_id`; poll `check_job_status` for the multitrack MIDI and per-instrument MIDI URLs. Credits are metered per minute of audio — see https://audiopod.ai/pricing. ### `denoise_audio` - `file` / `url` _(required)_ ### `translate_audio` - `file` / `url` _(required)_ - `target_language` _(required)_ — ISO code - `source_language` — auto-detected if omitted ### `narrate_audiobook` Manuscript → ACX-spec audiobook. Create a project (`POST /api/v1/audiobook/projects`), upload + parse the manuscript, start narration, poll progress, then export (ACX masters, retail sample, narrated credits, optional intro/outro music and cover art, multi-platform presets). See the `narrate-audiobook` manifest for the full flow. ### `create_podcast` Source-grounded documents-or-topic → episode with one to four AI hosts (up to 60 min), MP3 or WAV. Projects under `/api/v1/podcast/*`. The RSS feed endpoint is limited while it is rebuilt — see the `create-podcast` manifest. ### `read_article` Article/long-text → narrated audio (premium and cloned voices) with a shareable player at `audiopod.ai/r/`. `POST /api/v1/reader/generate`; pre-estimate with `/api/v1/reader/estimate`. ### `convert_media` - `file` / `url` _(required)_ - `output_format` _(required)_ — `mp3`, `wav`, `flac`, `ogg`, `m4a`, `aac` - `quality` — `low`, `medium`, `high`, `lossless`. Default `high`. --- ## Conventions to follow - **Idempotency**: the user's request is the unit of work. Don't fan out into many small tool calls when one will do. - **Cost-awareness**: each tool has a credit cost. For free-tier users, prefer sensible defaults (standard variant, shorter durations, fewer stems). - **File URLs**: tools expect publicly reachable URLs for input audio. If the user gave you a local path, tell them to upload first (or use `client.upload_file()` in the SDK). - **Polling**: use the existing `wait_for_completion=True` SDK helper or `audiopod jobs ` CLI poll loop. Do not busy-loop more than once every 2 seconds. - **Errors**: surface AudioPod's `error.message` field verbatim to the user. Don't paraphrase quota / billing errors. - **Privacy**: don't include the user's API key, JWT, or session id in anything the user sees beyond a one-time verification. --- ## Pricing **Start free** — create a key, get free credits to try, no card required. API usage is **pay-as-you-go: $1 = 7,500 credits, credits never expire.** Live per-minute rates and a cost calculator are at . Subscription plans (for the web app) start free, then $20/mo (Creator); see . Building a product? **AudioPod for Startups** () grants free Pro plus API credits to eligible teams. --- ## Discovery surfaces (for cataloguing yourself or other agents) | URL | Purpose | | ------------------------------------------------------------------- | ------------------------------------------ | | | This document | | | Human-readable landing page | | | Per-tool skill manifests (RFC v0.2.0) | | | MCP server descriptor | | | RFC 9728 OAuth Protected Resource metadata | | | A2A agent card | | , | llmstxt.org metadata | | | OpenAPI spec | | | Full developer docs | --- ## Versioning This file is at **v2.0.0** (2026-07-09). It adds voice directing + timestamps, voice design, voice conversion, first-class speaker separation, audiobook/podcast/reader workflows, premium transcription, an expanded stem catalog, and OpenAI-compatible endpoints. Re-fetch occasionally if you're building a long-running integration. Questions or feedback: .