Producer Audios Generation API 对接说明
内容提要
本文介绍Producer Audios Generation API的对接方法。用户需先在Ace Data Cloud控制台获取API Token，通过设置action、model、prompt或lyric等参数生成音乐。API支持自定义歌词、翻唱、续写、音乐变换、替换片段、伴奏/人声翻版及词曲分离等操作，并支持异步回调。文章详细说明了各操作参数、请求示例及错误处理方式。
延伸解读
参数调优要点
API 提供多个强度参数用于控制生成效果：lyrics_strength 控制歌词影响（0-1，默认0.7），sound_strength 控制音频提示词影响（0.2-1，默认0.7），cover_strength 控制翻唱强度（0.2-1，默认1），weirdness 控制风格奇特度（0-1，默认0.5）。开发者可根据需求调整这些参数，例如在续写示例中，通过降低 sound_strength 和 lyrics_strength 来平衡新旧内容。
异步回调与任务关联
由于音乐生成耗时较长，API 支持异步回调。设置 callback_url 后，请求立即返回 task_id，任务完成时结果会以 POST JSON 形式发送到该 URL，并包含相同的 task_id，便于关联。若不想提供回调地址，可设置 async 为 true，通过任务查询接口轮询获取结果。这有助于避免长时间 HTTP 连接占用资源。
错误码与排查建议
API 返回标准错误码：400 表示参数缺失或无效（如 token_mismatched、api_not_implemented），401 表示 token 无效，429 表示请求超限，500 表示服务器内部错误。开发者应检查请求参数、token 有效性及调用频率，并根据错误信息调整。示例中 500 错误返回 message 为 "fetch failed"，可能涉及网络或上游服务问题。
Q&A
如何获取 Producer Audios Generation API 的 API Token？
需要先到 Ace Data Cloud 控制台获取 API Token。如果尚未登录或注册，会自动跳转到登录页面，注册登录后返回当前页面即可获取。一个 API Token 即可调用平台所有服务，首次申请会赠送免费额度。
Producer Audios Generation API 支持哪些操作？对应的 action 参数值是什么？
支持生成（generate）、自定义歌词（generate）、翻唱（cover）、续写（extend）、音乐变换（variation）、替换片段（replace_section）、伴奏翻版（swap_instrumentals）、人声翻版（swap_vocals）和词曲分离（stems）。对于上传的歌曲，还有 upload_cover、upload_extend、upload_replace_section 等操作。
如何通过 API 生成一首自定义歌词的歌曲？
设置 action 为 generate，model 选择模型（如 FUZZ-2.0 Pro），custom 设为 true，在 lyric 字段传入歌词文本，并可设置 title 等参数。例如：curl -X POST 'https://api.acedata.cloud/producer/audios' -H 'accept: application/json' -H 'authorization: Bearer {token}' -H 'content-type: application/json' -d '{"action":"generate","model":"FUZZ-2.0 Pro","instrumental":false,"lyric":"[Verse]...","custom":true}'
如何对已有歌曲进行翻唱？
设置 action 为 cover，audio_id 为要翻唱的歌曲 ID，lyric 为新歌词，custom 可设为 true，title 可自定义。例如：curl -X POST 'https://api.acedata.cloud/producer/audios' -H 'accept: application/json' -H 'authorization: Bearer {token}' -H 'content-type: application/json' -d '{"action":"cover","model":"FUZZ-2.0 Pro","lyric":"...","audio_id":"38d3b9e2-0dfb-4338-b2a7-15e45656ed32","instrumental":false,"custom":true,"title":"Cover"}'
如何续写一首歌曲？
设置 action 为 extend，audio_id 为要续写的歌曲 ID，continue_at 指定从第几秒开始续写，还可调整 weirdness、sound_strength、lyrics_strength 等参数。例如：curl -X POST 'https://api.acedata.cloud/producer/audios' -H 'accept: application/json' -H 'authorization: Bearer {token}' -H 'content-type: application/json' -d '{"action":"extend","model":"FUZZ-2.0 Pro","instrumental":false,"lyric":"...","continue_at":3,"audio_id":"38d3b9e2-0dfb-4338-b2a7-15e45656ed32","custom":true,"title":"Extend","weirdness":0.3,"sound_strength":0.3,"lyrics_strength":0.6}'
如何实现异步回调？
在请求中设置 callback_url 字段，API 会立即返回 task_id，任务完成后会以 POST JSON 形式将结果发送到 callback_url，结果中包含 task_id 用于关联。也可以设置 async 为 true，接口立即返回 task_id，然后通过任务查询接口轮询获取结果。
API 返回的错误代码有哪些？分别代表什么？
400 token_mismatched：请求参数缺失或无效；400 api_not_implemented：请求参数缺失或无效；401 invalid_token：授权 token 无效或缺失；429 too_many_requests：请求频率超限；500 api_error：服务器内部错误。
