API 文档 / Trellis 音乐生成（ACE-Step 1.5）

API 文档 · Trellis 音乐生成（ACE-Step 1.5）

模型 ID：trellis-music

接口

POST /v1/musicmultipart/form-data提交音乐生成任务

GET /v1/jobs/{id}查询任务状态与结果

POST /v1/jobs/{id}/cancel取消任务（canceling → canceled；不计费）

调用方式

同步：直接 POST 返回结果（建议超时 1800s）；超时后请勿自动重试。

异步（推荐）：POST 加请求头 X-Trellis-Async: 1 → 返回 202 {id, poll}；轮询 GET /v1/jobs/{id}（间隔 5–10s）。

请求参数：

参数	类型	必填	默认	说明
`model`	string	是	trellis-music	固定 trellis-music
`caption`	string	是	—	音乐风格 / 情绪 / 编曲描述
`lyrics`	string	否	—	歌词（可含 [verse]/[chorus] 段落标记）；纯音乐留空并设 instrumental=true
`instrumental`	boolean	否	false	是否纯音乐（无人声）
`duration`	number	否	-1	时长（秒），如 30 / 60 / 120；无法确定时传 -1，由模型按歌词自动决定
`bpm`	integer	否	—	速度（可选）
`keyscale`	string	否	—	调式（可选）
`vocal_language`	string	否	auto	人声语言，如 zh / en（可选）
`inference_steps`	integer	否	—	推理步数（可选）
`guidance_scale`	number	否	—	引导强度（可选）
`shift`	number	否	—	调度 shift（可选）
`seed`	integer	否	—	随机种子（可选）
`batch_size`	integer	否	1	生成条数（可选）
`audio_format`	string	否	flac	输出格式（可选）
`lm_temperature`	number	否	0.8	5Hz LM 采样温度；越低越稳、越少重复/改序（可选）
`lm_cfg_scale`	number	否	2.5	LM CFG 强度；越高越贴合 caption/lyrics（可选）
`lm_top_k`	integer	否	0	LM top-k；0 表示不限（可选）
`lm_top_p`	number	否	0.9	LM 核采样（可选）
`use_cot_lyrics`	boolean	否	false	LM 是否改写歌词；设为 false 可禁止改写（可选）
`use_constrained_decoding`	boolean	否	true	约束结构化输出，段落顺序更稳（可选）
`thinking`	boolean	否	true	是否走 LM thinking（false 更贴歌词顺序，音乐性可能下降）（可选）
`infer_method`	string	否	ode	ode 确定性 / sde 随机（可选）
`lm_negative_prompt`	string	否	""	LM 负向提示（与 lm_cfg_scale 配合生效）（可选）

响应示例：

# 提交（异步）
{ "id": "<job>", "status": "queued" }

# 查询
{ "id": "<job>", "status": "completed",
  "url": "/v1/files/music/<name>.flac",
  "urls": ["/v1/files/music/<name>.flac"],
  "usage": { "seconds": 30, "sample_rate": 48000, "seed": 1234 } }

所有模型共用同一 API Key 与同一端点：https://api.trellis.hk/v1