音乐生成

LoopToken 音频 API 使用统一的异步任务协议。提交生成请求后会立即返回本地任务 ID；客户端轮询任务，成功后通过鉴权下载端点获取音轨。

接口地址

POST /v1/audio/music/generations
GET  /v1/audio/tasks/{task_id}
GET  /v1/audio/tasks/{task_id}/tracks/{track_index}/content

所有接口都需要 API Key：

Authorization: Bearer sk-lt-...

生成音乐

POST /v1/audio/music/generations
Content-Type: application/json

请求字段

字段	类型	必填	说明
`model`	string	是	当前为 `music-1`
`mode`	string	否	`description` 或 `lyrics`，默认 `description`
`prompt`	string	视模式	歌曲描述；`description` 模式必填，最多 1000 字符
`lyrics`	string	视模式	歌词；`lyrics` 模式且非纯音乐时必填，最多 5000 字符
`title`	string	否	歌曲标题，仅 `lyrics` 模式使用
`style`	string	否	期望的曲风、情绪、乐器或节奏，仅 `lyrics` 模式使用
`negative_style`	string	否	不希望出现的曲风或声音特征，仅 `lyrics` 模式使用
`instrumental`	boolean	否	是否生成纯音乐，默认 `false`
`vocal_gender`	string	否	`auto`、`male` 或 `female`，默认 `auto`
`style_strength`	number	否	曲风遵循强度，范围 `0` 到 `1`，仅 `lyrics` 模式使用
`creativity`	number	否	创意变化程度，范围 `0` 到 `1`，仅 `lyrics` 模式使用

description 模式用于从自然语言描述自动完成歌曲创作；lyrics 模式用于按指定歌词、标题和曲风生成。两种模式的输入字段互斥：描述模式不能传 lyrics，歌词模式不能传 prompt。

描述生成示例

curl https://api.vibelab.me/v1/audio/music/generations \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-1",
    "mode": "description",
    "prompt": "深夜城市的 lo-fi 钢琴，细雨声，舒缓而克制",
    "instrumental": true
  }'

自定义歌词示例

curl https://api.vibelab.me/v1/audio/music/generations \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-1",
    "mode": "lyrics",
    "title": "沿江夜行",
    "lyrics": "[Verse]\n路灯落进安静的江面\n[Chorus]\n我们向着天亮以前",
    "style": "独立流行，温暖女声，中速",
    "negative_style": "重金属，高失真",
    "vocal_gender": "female",
    "style_strength": 0.7,
    "creativity": 0.4
  }'

提交成功返回 HTTP 202：

{
  "id": "at_0198f0a0-1111-7777-8888-999999999999",
  "object": "audio.music.generation.task",
  "model": "music-1",
  "status": "pending",
  "progress": 0,
  "created_at": 1785902400
}

查询任务

建议每 3 到 5 秒轮询一次：

curl https://api.vibelab.me/v1/audio/tasks/at_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY"

任务状态为：

状态	说明
`pending`	已提交或正在排队
`running`	正在生成
`succeeded`	已完成，可以下载音轨
`failed`	生成失败，不会收取本次生成费用

成功任务返回一个或多个音轨：

{
  "id": "at_0198f0a0-1111-7777-8888-999999999999",
  "object": "audio.music.generation.task",
  "model": "music-1",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1785902400,
  "completed_at": 1785902478,
  "credits_charged": 0.6,
  "tracks": [
    {
      "id": "track_1",
      "title": "沿江夜行",
      "duration": 128.5,
      "lyrics": "[Verse]...",
      "style": "indie pop, warm",
      "audio_url": "/v1/audio/tasks/at_0198f0a0-1111-7777-8888-999999999999/tracks/1/content"
    }
  ]
}

audio_url 是相对于 API Base URL 的平台下载路径，不是永久公开链接。请求该路径时仍需携带同一 API Key；任务和音轨只能由所属账户访问。音轨可下载时请及时保存到自己的持久化存储，不要把该路径作为长期资源地址。

完整轮询示例

import time
import os
import requests

BASE_URL = "https://api.vibelab.me"
LOOPTOKEN_API_KEY = os.environ["LOOPTOKEN_API_KEY"]
headers = {"Authorization": f"Bearer {LOOPTOKEN_API_KEY}"}

response = requests.post(
    f"{BASE_URL}/v1/audio/music/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "music-1",
        "prompt": "明亮的电子流行配乐，适合产品发布视频",
        "instrumental": True,
    },
)
response.raise_for_status()
task = response.json()

while task["status"] not in ("succeeded", "failed"):
    time.sleep(4)
    response = requests.get(f"{BASE_URL}/v1/audio/tasks/{task['id']}", headers=headers)
    response.raise_for_status()
    task = response.json()

if task["status"] == "failed":
    raise RuntimeError(task["error"])

track = task["tracks"][0]
audio = requests.get(f"{BASE_URL}{track['audio_url']}", headers=headers)
audio.raise_for_status()
with open("track.mp3", "wb") as file:
    file.write(audio.content)

计费

music-1 按成功生成任务固定计费。提交时预扣，任务成功后结算；失败或超时自动退款。一次任务返回多条音轨时仍按一次任务计费。实际扣费以终态任务中的 credits_charged 和定价页为准。

错误

HTTP 状态	`code`	说明
`400`	`invalid_request_error`	JSON、字段类型、模式组合或参数范围不合法
`402`	`insufficient_credits`	余额不足
`404`	`model_not_found`	模型不存在或当前不可用
`404`	`task_not_found`	任务不存在或不属于当前账户
`404`	`track_not_found`	音轨不存在、任务尚未成功或不属于当前账户
`502`	`upstream_error`	音频服务暂时不可用
`503`	`no_available_channel`	当前没有可用的音频生成通道

失败任务中的 error.code 为 generation_failed 或 timeout。平台不会在响应中返回内部路由、原始错误或临时资源地址。

音乐生成

本页内容