# Taoyuan (桃源) — a finished song for one person

> Taoyuan turns one sentence ("a warm birthday song for my mom who loves singing in the kitchen") into a finished song: title, lyrics that only use what the user said, English style tags, cover art and two full candidate tracks, in about three minutes. It is available as a REST API, an MCP server, and a website. Lyrics can be in Chinese, Cantonese, English or Japanese. Songs can be up to 6 minutes; instrumental-only is supported; you can redo one section of a finished song or split it into stems.

Base URLs
- API: https://api.musicsforyou.com
- MCP (Streamable HTTP): https://api.musicsforyou.com/mcp
- Website / keys / purchase: https://www.musicsforyou.com/developers
- OpenAPI 3.1: https://api.musicsforyou.com/openapi.json
- OpenAPI 3.0.3 (for Coze/扣子, Dify and other importers): https://api.musicsforyou.com/openapi-coze.json
- Full guide: https://www.musicsforyou.com/llms-full.txt
- Source / Claude Desktop package / examples: https://github.com/JerryYangAI/taoyuan-mcp (npm: taoyuan-mcp)

Authentication
- Create an API key at https://www.musicsforyou.com/developers (sign in first). Keys start with `ty_live_`. New keys come with 3 free credits.
- Send it as `Authorization: Bearer ty_live_...` on every request (REST and MCP).
- Connector platforms (ChatGPT, claude.ai) can add the MCP URL and sign in when prompted instead of pasting a key.

Billing (simple rules)
- 1 credit = one generation = one song with two candidate tracks.
- Costs 1 credit: `POST /v1/generations` (generate_music), `POST /v1/songs` (create_song), `POST /v1/generations/{id}/replace-section` (replace_section).
- Free: compile, revise, lint, get, list, presets, capabilities, credits, usage.
- Stems: 2-track vocal/instrumental split is free once per song for non-members and unlimited for members; 12-stem split is Pro only. Neither costs credits.
- API and MCP calls use prepaid API credits only. Failed generations are refunded automatically.
- Packs: api-100 ¥300 / 100 credits; api-10-usd US$9.90 / 10; api-50-usd US$39 / 50. Buy at https://www.musicsforyou.com/developers.

Quick start — MCP (one curl)
curl -s https://api.musicsforyou.com/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer ty_live_...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_credit_balance","arguments":{}}}'

Claude Code: claude mcp add --transport http taoyuan https://api.musicsforyou.com/mcp --header "Authorization: Bearer ty_live_..."

Quick start — REST, one shot (compile + generate + wait in one call)
curl -s https://api.musicsforyou.com/v1/songs \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer ty_live_...' \
  -d '{"text":"A warm birthday song for my mom who loves singing in the kitchen","uiLanguage":"en","waitSeconds":120}'
# 200 when finished, 202 if still running (then GET /v1/generations/{id}?waitSeconds=60)
# generation.clips[0].audioUrl, generation.clips[1].audioUrl, generation.coverUrl

Quick start — REST, step by step (preview lyrics before spending a credit)
1. POST /v1/prompts/compile  {"text":"...","uiLanguage":"en"}  -> {"spec":{...}}  (free)
   - spec.status = "ready": show spec.rendered.title / lyrics / style to the user
   - spec.status = "needs_input": ask spec.question.question, call again with "clarificationAnswer"
   - to change something: POST /v1/prompts/revise {"spec":spec,"instruction":"stronger chorus"} (free)
2. POST /v1/generations  {"spec":spec,"idempotencyKey":"order-123"}  -> 202 {"generation":{"id":...}}  (1 credit)
3. GET /v1/generations/{id}?waitSeconds=60  until generation.status is "finished" (or "failed"); or SSE at /v1/generations/{id}/events

MCP tools (same names as OpenAPI operationIds)
compile_music_prompt (free) · revise_generation_prompt (free) · generate_music (1 credit) · get_generation (free) · replace_section (1 credit) · separate_stems (see billing) · list_tracks (free) · list_presets (free) · get_credit_balance (free)

Errors: every failure is {"success":false,"code":"...","error":"..."}. Branch on code: LOGIN_REQUIRED, INVALID_API_KEY, NEED_TOPUP (buy credits), SPEC_INVALID, COMPILE_LIMIT, RATE_LIMIT_EXCEEDED, GENERATION_NOT_FOUND, PRO_REQUIRED, PROVIDER_TIMEOUT.

Rate limits: generation submissions 5/min per IP; compile and revise 30/hour per account (guests 5/day per IP).

Rules: do not submit lyrics you do not own; prohibited content is screened. Songs generated through the API may be used commercially by the key owner. Support: 2368082693@qq.com. Terms: https://www.musicsforyou.com/terms