Skip to main content

​
Endpoint

POST /api/v1/music/generate
This is an asynchronous endpoint. It returns a task_id immediately. Use Get Task to poll for results.

​
Request body

FieldTypeRequiredDescription
promptstringSee noteLyric content or song description. Supports Chinese and English. Required unless tags or gpt_description_prompt is provided.
titlestringNoTrack title.
tagsstringSee noteStyle tags (e.g. "pop upbeat female vocals" or "流行 治愈 女声"). Required unless prompt or gpt_description_prompt is provided.
gpt_description_promptstringSee noteInspiration mode. Describe the song in natural language instead of writing lyrics (e.g. "An upbeat Chinese pop song about summer and friendship"). Cannot be used together with prompt/tags.
make_instrumentalbooleanNoGenerate an instrumental track (no lyrics). Default false.
persona_idstringNoAI singer persona ID. Apply a custom vocal style trained from a specific clip. Get this ID from Create Persona.
continue_clip_idstringNoExtend an existing clip. Provide the clip ID to continue from.
continue_atintegerNoPosition in seconds to start the extension from. Only used with continue_clip_id.
callback_urlstringNoURL to receive a webhook callback when the task completes.
retention_daysintegerNoHow many days to keep audio files. Default 7, max 30.
At least one of prompt, tags, or gpt_description_prompt is required. gpt_description_prompt cannot be combined with prompt or tags.

​
Language support

All text fields (prompt, title, tags, gpt_description_prompt) support Chinese and English. 
{
  "prompt": "[主歌]\n风吹过树梢\n阳光洒在肩头\n[副歌]\n我在这里等你回来",
  "title": "等你回来",
  "tags": "流行 抒情 女声"
}

​
Response

{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
FieldTypeDescription
task_idstringUse this to poll Get Task for results.
statusstringInitial status — always "queuing".

​
Examples

Custom mode (lyrics + tags): 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[Verse]\nSilent stars above\nGuiding me tonight\n[Chorus]\nForever in the light",
    "title": "Starlight",
    "tags": "pop dreamy female vocals",
    "callback_url": "https://yourserver.com/webhooks/music"
  }'
Inspiration mode (natural language description): 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt": "A calm Chinese folk song about missing home, gentle guitar, female voice"
  }'
With a custom AI singer persona: 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[Verse]\nRainy nights remind me of you\n[Chorus]\nCome back to me",
    "tags": "rnb slow female",
    "persona_id": "persona-abc123"
  }'
Extend an existing clip: 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[Bridge]\nThe story continues here",
    "tags": "pop",
    "continue_clip_id": "clip-abc123",
    "continue_at": 60
  }'

​
Typical flow

  1. Call this endpoint → receive task_id
  2. Poll POST /api/v1/task/{task_id} every 5 seconds
  3. When status = "completed", read results[].audio_url
  4. Files expire after retention_days — download promptly