Trellis AITrellis AI
API 指南 / Trellis 音乐生成（ACE-Step 1.5）

API 指南 · Trellis 音乐生成（ACE-Step 1.5）

文生歌曲 / 音乐：文本描述（可选歌词）→ 带人声完整歌曲（异步），按音频秒计费。

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

以 multipart/form-data 提交：caption（风格 / 情绪 / 编曲，必填）、可选 lyrics（歌词；纯音乐留空并设 instrumental=true）、duration（秒，如 30 / 60 / 120；无法确定时传 `-1`，由模型按歌词自动决定）。

常用可调：bpm、keyscale、vocal_language（如 zh / en）、inference_steps、guidance_scale、shift、seed、batch_size、audio_format。

减少重复 / 乱序（关键）：歌词用 [Verse]/[Chorus]/[Outro] 标签（带编号的不同段落保留编号，如 [Verse 1]/[Verse 2]，不要都写成 [verse]，否则重复段会被折叠跳过），并让 duration 与歌词长度匹配（时长过长会触发“重复填充”，是重复主因）。注意网关 duration<=0 的自动估时用 ~4.5 字/秒、明显偏短，建议按 汉字数/2.5 估算后显式传入。进一步可用 use_cot_lyrics=false（禁止 LM 改写歌词）、lm_temperature（默认 0.8，越低越稳）、lm_cfg_scale（默认 2.5，越高越贴合歌词）、lm_top_k/lm_top_p、use_constrained_decoding=true、infer_method（ode 确定性 / sde 随机）、thinking（false 顺序更贴）、lm_negative_prompt。

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

按 usage.seconds 计费（¥0.002 / 秒）；产物 48kHz flac。

调用示例：

cURL（异步）
ID=$(curl -s https://api.trellis.hk/v1/music \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "X-Trellis-Async: 1" \
  -F model=trellis-music \
  -F "caption=轻快的中文流行，男声" \
  -F $'lyrics=[verse]\n岁月如歌\n[chorus]\n一起唱' \
  -F duration=30 | 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