常见问题

如何获取 API Key？

登录控制台后，进入左侧「API Keys」页面，点击「创建 API Key」，输入名称后确认。创建成功后请立即复制保存完整密钥，关闭弹窗后将不再显示。

余额不足时会怎样？

当账户余额不足以支付当前请求时，接口会返回 Insufficient account balance 错误码（HTTP 402）。

建议在客户端做如下处理：

捕获 402 状态码并展示友好提示（如「余额不足，请前往充值」）。
预留一定的余额缓冲，避免因计费精度问题导致偶发失败。

生成任务需要多久？

任务耗时取决于模型复杂度、音频时长和当前队列长度：

任务类型	平均耗时	说明
标准歌曲生成	90~120 秒	常规 prompt，默认时长
带参考音频	90~180 秒	需要额外的风格分析

建议

不要在客户端同步等待任务完成。提交任务后返回 task_id，由服务端异步轮询或回调获取结果。

歌曲是否支持流式返回？

生成的歌曲在流式状态（生成中）时，可以流式获取歌曲音频内容，请使用歌曲信息中返回的流式音频链接地址获取。

如何接收歌曲状态回调？

提交生歌 / 仿写 / 扩写任务时，可在请求体中传入 callback 回调地址。歌曲状态变更时，平台会向该地址发送 POST 通知。

回调请求体字段

字段	类型	说明
`song_id`	UUID	歌曲 ID
`task_id`	UUID	任务 ID
`status`	string	歌曲状态
`update_at`	int	状态更新时间戳
`pipe_url`	string	流式播放地址
`audio_url`	string	完整 MP3 播放地址
`title`	string	歌名
`lyric`	string	歌词
`error`	string	错误原因
`error_code`	int	错误代码

回调示例

{
  "song_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "done",
  "update_at": 1710000000,
  "pipe_url": "",
  "audio_url": "https://example.com/audio.mp3",
  "title": "半透明的薄雾",
  "lyric": "[VERSE]\\n赤脚踩碎细浪的光\\n...",
  "error": "",
  "error_code": 0
}

说明

仅当状态变为 running运行中、stream可流式播放、done生成成功、fail生成失败 时会触发回调；pending排队中、cancelled已取消 不会主动推送。建议回调接口尽快返回 200，耗时处理放到异步队列中。

如何申请发票？

目前发票管理功能正在开发中。如需开具发票，请联系商务团队提供充值记录和开票信息，我们将人工处理。

免费额度 / 试用吗？

新注册用户暂无自动免费额度。如需试用，请通过控制台充值开始调用。企业用户可申请商务对接，获取定制化试用方案。

报错 `Concurrency limit reached` 怎么办？

收到 429 状态码表示当前请求频率超过了账户的并发或 QPS 限制。建议：

指数退避重试

首次延迟 1 秒重试，后续每次翻倍，最多重试 3 次。

控制并发

检查当前同时进行的任务数，确保不超过账户并发档位。

并发说明

当前歌曲生成任务的并发控制实现的逻辑是，根据用户账号维度，检查当前未完成的歌曲加上本次请求需要生成的歌曲的总数，如果超过并发上限，则拒绝本次请求。当前同一付费用户账号同时生成歌曲的并发数上限为10首歌。

歌词（lyric）怎么写？

歌词使用 \n 换行分隔。可使用结构标签标记段落，标签需为大写并带方括号，例如 [VERSE]、[CHORUS]。

当前支持的结构标签：

标签	含义
`[INTRO]`	前奏
`[VERSE]`	主歌
`[CHORUS]`	副歌
`[BRIDGE]`	桥接
`[BREAK]`	间奏
`[OUTRO]`	尾奏

示例：

[INTRO]

[VERSE]
赤脚踩碎细浪的光
海风偷走发梢的谎

[CHORUS]
阳光是跳动的糖粒
咸味在舌尖轻轻游弋

[BRIDGE]
潮声慢下来
海平线踮起脚尖

[OUTRO]

还有更多问题？

如果以上未解决你的问题，请通过以下方式联系我们：

技术问题：在控制台提交工单联系我们
商务合作：发送邮件至 customerservice@ycyx.tech