跳转到主要内容
通过 POST /acemusic/audios 从灵感或自定义歌词创作歌曲、导入参考音频、翻唱已有作品,或融合两首参考。歌曲创作、翻唱和融合各以两首候选为一组;音频上传导入一首参考。两类操作分别计费。

获取凭据

在 控制台 开通 ACE Music,或使用已获该服务权限的通用应用凭据。请求携带 Authorization: Bearer YOUR_API_KEY。应用余额、凭据限额和服务权限均会检查。

灵感模式

action 默认为 generate。可选模型为 acemusic-v1.1(默认)和 acemusic-v1。

自定义模式

在 generate 中将 custom 设为 true,提供 title、lyric 和 style。歌词可包含 [Verse]、[Chorus] 等段落标签,也可先通过 歌词生成 API 创作,再编辑后提交。

上传参考音频

使用同一个歌曲接口,设置 action=upload 与有效的 HTTPS audio_url,可选 name。当前参考导入仅支持 MP3 文件。此操作不需要 model、custom 或歌词字段。只上传并准备参考,不会自动再生成歌曲。 以下为请求示例;请替换为自己有权使用的音频地址:
若希望将新参考与某首已有作品组合使用,可在上传时传入该作品的平台 audio_id。上传完成后的 data 包含一首音轨,其 id 可用于翻唱或融合。将本地文件上传到文件服务与本接口的参考导入是不同操作,参考导入成功后按上传价格收费。

翻唱与双参考融合

这两种操作使用 acemusic-v1.1,默认仍为该模型。填写 lyric、style,可选 title;不要再传 custom 或灵感 prompt。audio_influence 控制音频参考程度,范围为 1–100,默认 60。当前不接受风格强度、纯音乐、续写、分轨或音色参数。 cover 使用一个自己可访问的平台音轨 audio_id。请从先前成功任务的 response.data[*].id 取值;它不是生成任务的 task_id。以下 ID 是需要替换的请求占位值,不是示例结果。
mashup 使用 mashup_audio_ids,当前要求恰好两首不同的平台音轨。参考可来自已完成的上传或歌曲任务,必须属于自己可访问且相互兼容的作品;不兼容的组合会被拒绝。

通用字段

任务与交付

保存提交返回的 task_id,通过 任务 API 查询。提交受理仅表示任务已建立。type=audios 的历史同时包含四种操作。完整结果的 data 是音轨列表,每首包含平台音轨 id、model、state、title、lyric、style、实际 duration(秒)、audio_url 和可选 image_url。 上传成功时交付一首参考;生成、翻唱或融合须在两首音频均可交付后才将整个组标记为成功。部分失败保留已完成的音轨,任务标记为 partial_failed;封面缺失不影响已有音频播放。浏览器刷新、网络中断后应查询原任务,不要再次提交生成或上传。 同一 Idempotency-Key 与同一请求内容返回原任务;使用同键发送不同内容会冲突。超时且受理状态不明确时保留该键和原任务身份,等待查询或联系支持,不要换键自动补发。

费用

生成、翻唱与融合按完整双曲组收费,每组只收一次,最终失败或部分失败的任务不收生成费。上传参考是独立的收费操作,成功导入一首参考收一次上传费,最终失败不收费。查询免费;歌词助手也独立收费,歌曲操作不会隐式另收歌词助手费用。 完整双曲组为 0.314816994048 Credits,成功上传参考为 0.0157408497024 Credits。按 2026-11-17 的最大套餐与汇率基准,分别折合人民币 ¥0.20 和 ¥0.01。实际价格与折算以控制台对应套餐、优惠、站点定价和汇率为准。

回调与错误

完成后向 callback_url 推送最终任务结果。接收方应按 task_id 去重并返回成功状态;回调可能重投。回调接收失败不会重新生成、重新导入或额外扣费,仍可使用任务 API 获取结果。 参数无效或参考不兼容返回 400;认证或权限问题返回 401/403;余额不足返回 402;限流返回 429;服务失败返回 500。异步执行错误通过任务终态和 error 表达。排查时提供 task_id 与 trace_id。