API 文档

将余音 AI 音乐生成能力集成到你的应用中

认证

所有 API 请求需在 HTTP 请求头中携带 Bearer Token。工作室版用户可在个人资料页获取 API 密钥。

Authorization: Bearer YOUR_API_KEY

生成音乐

POST/api/generate

创建一个音乐生成任务，返回 job_id 用于查询进度。

请求体

{
  "prompt":     "一首温暖的母亲节歌曲",   // 必填，描述文本（≤ 500 字）
  "genre":      "pop",                    // 音乐风格，见下方风格列表
  "voice_type": "female_pop",            // 声音类型，见下方声音列表
  "duration":   60,                      // 时长（秒），30 / 60 / 90 / 120 / 180
  "language":   "zh"                     // 语言：zh 或 en
}

响应

{
  "job_id":            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status":            "queued",
  "title":             null,
  "estimated_seconds": 45
}

查询任务状态

GET/api/status/{job_id}

轮询任务进度。建议每 3 秒查询一次，直到 status 变为 completed 或 failed。

{
  "job_id":        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status":        "completed",   // queued | processing | completed | failed
  "progress":      100,           // 0-100
  "title":         "亲爱的妈妈",
  "lyrics":        "...",
  "audio_url":     "/audio/xxx.mp3",
  "audio_duration": 62.4,
  "error":         null
}

生成历史

GET/api/history?page=1&page_size=20

获取当前用户的生成历史，分页返回。

枚举值

声音类型

female_pop   // 女声流行
male_pop     // 男声流行
children     // 儿童声
instrumental // 纯音乐

音乐风格

pop       // 流行
folk      // 民谣
rap       // 说唱
classical // 古典
nursery   // 儿歌
rock      // 摇滚
jazz      // 爵士
rnb       // R&B
electronic// 电子

速率限制

免费版10 次 / 月

专业版200 次 / 月

工作室版无限次

需要 API 密钥或定制集成？

联系我们 →