瑞祥API 接入文档

用户在网站注册账号。瑞祥音乐桌面软件使用网站账号和密码登录；独立开发者可在工作台申请 API Key。积分充值请联系瑞祥客服。

桌面软件登录

瑞祥音乐软件调用 POST /v1/auth/login，提交网站注册的邮箱和密码，取得有效期 30 天的会话令牌；后续请求使用 Authorization: Bearer 会话令牌。软件不提供注册入口，也不要求填写 API Key。退出登录调用 POST /v1/auth/logout。

认证和余额

所有接口使用 HTTPS。独立开发者在请求头使用 Authorization: Bearer 你的瑞祥API Key；瑞祥音乐软件使用登录后的会话令牌。GET /v1/balance 返回 {"balance":10}。

提交生成

POST /v1/generations，JSON 请求体：

{"request_id":"唯一任务号至少8字符","title":"歌曲标题","prompt":"歌词全文","tags":"伤感情歌","negative_tags":"","vocal_gender":"auto","mv":"chirp-hawk","make_instrumental":false}

vocal_gender 可填 auto（自动）、male（男声）、female（女声）。瑞祥当前仅接入 V6：chirp-hawk、chirp-hawk-wild、chirp-goose。男声或女声会映射到 tags 中的 male vocal 或 female vocal；声线由模型生成，选择结果可能存在偏差。纯音乐模式须使用 auto。

返回 id、status、provider_ids、audio_urls、error。相同用户重复使用同一个 request_id 会返回原任务，不重复扣费。网络异常重试时必须沿用原编号。

声线请求示例

{"request_id":"song-male-001","title":"示例男声","prompt":"歌词全文","tags":"流行, 抒情","vocal_gender":"male","mv":"chirp-hawk"}

客户端只需提交上述字段并使用自己的瑞祥 API Key。

查询结果

GET /v1/generations/{id}。建议每 10 秒以上查询一次。状态包括 submitting、processing、completed、failed、needs_review。每个音频版本确认完成后即可公开对应的 audio_urls，生成中的临时流地址不会显示。网站和软件可在线预览，或下载到本地；网站只保存链接，不存音频。

计费和并发

提交时扣积分；提交未成功或全部版本失败时自动退款；如状态为 needs_review，请联系瑞祥客服。桌面软件最多同时跟踪 200 首，默认提交间隔 0 秒。200 是在途任务上限，并非每秒请求数。瑞祥会持续更新任务状态。单个版本完成后即可返回其正式音频链接；若其他版本仍在生成，页面显示“部分完成”。

错误