Trellis AITrellis AI
API 指南 / Trellis 歌曲生成（YuE2·符号化）

API 指南 · Trellis 歌曲生成（YuE2·符号化）

符号化歌曲生成（YuE2）：风格 + 歌词 → 整首歌（含人声），并产出可复用 / 编辑的 ABC 曲谱（异步），按音频秒计费。

调用方式
同步：直接 POST 返回结果（建议超时 1800s）；超时后请勿自动重试。
异步（推荐）：POST 加请求头 X-Trellis-Async: 1 → 返回 202 {id, poll}；轮询 GET /v1/jobs/{id}（间隔 5–10s）。

以 multipart/form-data 提交：style（风格，必填）、可选 lyrics（歌词，支持 [Verse]/[Chorus]/[Bridge]/[Outro] 段落标记）、cot（full 默认 / melody / off）、seed（-1 随机）、abc（复用曲谱）。

同段落同曲谱（关键）：首次生成返回 score（ABC 文本）与 score_url；把该 abc 作为下次请求的 abc 传入并设 cot=melody，即可锁定旋律、让重复段落复用同一曲谱，避免“同类段落旋律不一致”。

带词曲谱：另返回 score_lyrics / score_lyrics_url——在 V: Vocal 轨的音符行下写入 w: 歌词行（逐音节，休止用 * 占位，仅 Vocal 轨加词）。供上游直接解析“词-音”对应，无需自行猜测。

建议异步：请求头 X-Trellis-Async: 1 → 202 {id,poll}，轮询 GET /v1/jobs/{id}；completed 后 url 为 /v1/files/yue2/<name>.flac、score_url 为 /v1/files/yue2/<name>.abc。

按 usage.seconds 计费。许可：YuE2 权重 CC BY-NC 4.0（非商用）。

调用示例：

cURL（异步）
ID=$(curl -s https://api.trellis.hk/v1/song \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "X-Trellis-Async: 1" \
  -F model=trellis-yue2 \
  -F "style=温暖的中文流行，男声" \
  -F $'lyrics=[Verse]\n机房的灯还亮着一盏\n[Chorus]\n小巧灵，小巧灵' | jq -r .id)

curl -s https://api.trellis.hk/v1/jobs/$ID -H "Authorization: Bearer sk-xxxxxxxx"
查看 API 文档模型信息与价格
所有模型共用同一 API Key 与同一端点：https://api.trellis.hk/v1