音乐

创建音乐

创建音乐、歌词或音效生成任务

POST
/v1/music/generations

生成音乐、歌词或音效。创建成功后会返回任务 ID,调用 GET /v1/tasks/{id} 获取最终结果。

不同模型接受的字段不同。发送可选字段前,先查看 GET /v1/models/{model};模型未列出的字段可能返回 400 unsupported_parameter。Suno 字段(mv、title、tags、negative_tags、audio_operation 及其配套字段)只适用于 Suno 模型。不支持 user,发送会返回 400。

请求体

modelstring默认值: suno-music

音乐模型 ID,例如 suno-music 或 stable-audio-3。请显式传入。仅生成歌词时,请选择当前公开操作包含 lyrics 的模型。

promptstring

音乐描述或替换文本。音乐、歌词、upload-cover、upload-extend 和 replace-section 请求必填;add-instrumental 和分轨请求可省略。

titlestring

生成歌曲的标题。

tagsstring

风格标签(例如 "pop, upbeat, electronic")。

negative_tagsstring

需要避开的风格。audio_operation 为 add-instrumental 时必填。

actionstring

可选值为 MUSIC 或 LYRICS。请选择支持对应公开操作的模型;此字段不会让仅支持音乐的模型具备歌词能力。

mvstring

Suno 版本选择器。生成、upload-cover、upload-extend、add-instrumental 以及以 audio_url 为源的替换请求必填。歌词、以 task_id + audio_id 为源的替换和分轨请求请省略。支持值: chirp-v6, chirp-v6-mini, chirp-v6-wild.

make_instrumentalboolean

设为 true 时生成无歌声的纯音乐。

audio_urlstring

可以从互联网访问的参考音频 URL。填写这个字段但省略 audio_operation 时,默认使用 upload-cover。

audio_operationstring

音频操作: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.

vocal-separate、multi-stem-separation 和 advanced-split 需要 task_id + audio_id;advanced-split 还需要 stem_name。upload-extend 需要大于 0 的 continue_at。add-instrumental 需要 audio_url、title、tags 和 negative_tags。

replace-section 必须提供 prompt、tags、title、infill_start_s、infill_end_s 和 full_lyrics。来源只能二选一:task_id + audio_id,或 audio_url + mv。替换区间必须为 6–60 秒。

task_idstring

本组织拥有的源任务 ID,用于生成音频的分段替换或分轨。

audio_idstring

源任务结果返回的音频 ID。替换已生成音频和分轨时,需要与 task_id 一起提供。

infill_start_snumber

替换区间的起始秒数,必须大于等于 0。replace-section 必填。

infill_end_snumber

替换区间的结束秒数。replace-section 必填,必须比 infill_start_s 晚 6–60 秒。

full_lyricsstring

结果歌曲的完整歌词。replace-section 必填。

stem_namestring

分轨名称。advanced-split 必填。

continue_clip_idstring

要续写的上一个片段的 ID。

continue_atnumber

续写起点,单位为秒。upload-extend 必填且必须大于 0。

durationinteger

生成音频的时长,单位为秒,1 到 380。仅适用于列出该参数的模型,例如 stable-audio-3;模型详情会给出各自的上限。

output_formatstring

模型列出的音频文件格式,例如 mp3、wav 或 flac。仅适用于列出该参数的模型。

seedinteger

用于复现结果的随机种子,0 到 4294967294。仅适用于列出该参数的模型。

stepsinteger

生成步数,范围因模型而异(例如 stable-audio-3 为 4 到 8)。仅适用于列出该参数的模型。

部分模型还列出 negative_prompt、n、seconds、guidance_scale 等字段。只有模型详情列出时才发送;所选模型不接受的字段会返回 400。

cfg_scalenumber

提示词引导强度,1 到 25。仅适用于列出该参数的模型。

prompt 最多 5000 字符,tags 和 negative_tags 各最多 1000 字符。可用操作和参数以所选模型的当前详情为准。

响应

idstring

用于查询状态的任务 ID。

task_idstring

同一个异步任务 ID 的别名,仅在返回时存在。

poll_urlstring

任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。

statusstring

任务状态:pending、processing、completed 或 failed。

createdinteger

任务创建的 Unix 时间戳,仅在返回时存在。

请求

curl -X POST "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": "An upbeat electronic dance track with heavy bass",
    "title": "Night Drive",
    "tags": "electronic, EDM, energetic"
  }'

下面是音效生成示例,使用的模型接受 duration 和 output_format,而不是 Suno 字段:

{
  "model": "stable-audio-3",
  "prompt": "Warm lo-fi beat with soft vinyl crackle",
  "duration": 30,
  "output_format": "mp3"
}

响应

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

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。

长度1 <= length <= 255

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json

application/json