媒体指南

音乐生成

生成歌曲或歌词,并等待最终音频

音乐生成是异步任务。POST /v1/music/generations 会返回任务 ID、状态,通常还会返回 poll_url。用这个 ID 调用 GET /v1/tasks/{id} 查询,直到任务变为 completed 或 failed。

选择要生成的内容

想生成什么关键字段说明
完整歌曲或伴奏model、mv、prompt,可选 title、tags、action: "MUSIC"最终会返回音频
只生成歌词model、prompt、action: "LYRICS"所选模型必须支持歌词生成
续写已有片段model、mv、prompt、continue_clip_id,可选 continue_at保存上一段音乐的片段 ID
翻唱或续写你自己的音频model、mv、prompt、audio_url,可选 audio_operationaudio_url 必须是公开 URL。audio_operation 默认是 upload-cover;upload-extend 还需要 continue_at
添加伴奏、替换片段或拆分分轨audio_operation:add-instrumental、replace-section、vocal-separate、multi-stem-separation 或 advanced-split每种操作有各自的必填字段,见创建音乐

用下面的请求获取当前音乐模型:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

下面的示例使用 suno-music,并把 mv 设为 chirp-v6。其他音乐模型(如 stable-audio-3)使用 duration、output_format 等不同字段,请先查看模型详情。只生成歌词时,请选择明确支持歌词的模型,发送 action: "LYRICS",并省略 mv。

创建音乐任务

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-music",
    "mv": "chirp-v6",
    "prompt": "一首充满活力的合成流行曲,伴有温暖的声乐和干净的合唱",
    "title": "晨间静电",
    "tags": "合成流行,充满活力",
    "action": "MUSIC"
  }'

提示词、标题和标签可能会出现在产品历史中,不要把 API 密钥、私密 URL 或诊断信息写进去。

获取生成结果

用返回的 id 或 task_id 调用 GET /v1/tasks/{id}。

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

创建响应

创建成功后会得到任务记录,此时音乐还没有完成:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno-music"
}

状态变为 completed 后,响应可能包含:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
  "video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
  "image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
  "title": "晨间静电",
  "lyrics": "[Verse 1]\n...",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
        "kind": "audio",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
        "kind": "video",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
        "kind": "image",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

下载地址只会在 status 变为 completed 后出现。失败时会返回 status: "failed" 和 error。媒体 URL 都是 TokenLab URL,有效期 30 天;需要更久保留的结果请下载或保存。

在产品中展示状态

  • 创建成功后显示“生成中”。
  • 耗时较长时每 5–10 秒查询一次,completed 或 failed 后停止。
  • 只有状态完成且存在 audio_url 时才显示播放器。
  • 只生成歌词时展示文字结果,不要让用户误以为会收到音频。
  • 页面刷新后继续查询已经保存的 task_id,不要重新创建。

费用记录

创建音乐任务时可能暂扣预估费用,完成或失败后记录最终金额。请保存 request_id、task_id、模型、API 地址和返回时的 billing_transaction_id;最终费用以 Management API 的 Usage 为准。

常见错误

症状可能原因修复
创建后没有播放器仍在生成,或完成时没有 audio_url查询到最终状态;没有音频时按失败处理
刷新后出现两首页面重新创建了任务保存并复用 task_id
歌词任务没有音频action: "LYRICS" 只返回文字歌词和音乐使用不同的界面
参数不支持所选模型不接受这个字段删除字段,或改用明确支持它的模型

API 参考

主题参考
创建音乐创建音乐
获取音乐状态获取音乐状态
获取任务状态获取任务状态
列出模型列出模型
计费与定价计费与定价

本页内容