Documentation Index
Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
Use this file to discover all available pages before exploring further.
本文将介绍一种 Fish Voices Generation API 对接说明，它是可以通过输入音频链接来创建自己的音色。
申请流程
要使用 API，需要先到 Fish Voices Generation API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：
如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。
在首次申请时会有免费额度赠送，可以免费使用该 API。
基本使用
首先先了解下基本的使用方式，就是输入音色的音频链接 voice_url，便可获得处理后的结果，具体的内容如下：
可以看到这里我们设置了 Request Headers，包括：
accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。authorization：调用 API 的密钥，申请之后可以直接下拉选择。
另外设置了 Request Body，包括：
voice_url：上传的音色音频链接。title：该音色的标题信息。image_urls：该音色的封面图片。description：该音色的描述信息。callback_url：需要回调结果的URL。
选择之后，可以发现右侧也生成了对应代码，如图所示：
点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：
{
"success": true,
"task_id": "b01db503-dd9e-4f92-861a-344f14756217",
"trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
"data": {
"_id": "d5d21261512b4852b9ccd709facf93f3",
"type": "tts",
"title": "test",
"description": "test",
"cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
"train_mode": "fast",
"state": "trained",
"tags": [],
"samples": [
{
"title": "Default Sample",
"text": "通过长期观察发现，珊瑚礁生态系统中的鱼类具有复杂的群体行为模式。它们利用色彩变化和特定的游动姿态来传递信息，这种精密的非语言交流系统展现了海洋生物的适应智慧。",
"task_id": "4ae961828fc94c07b2103dc039a8466b",
"audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
}
],
"created_at": "2025-09-21T07:29:41.058506Z",
"updated_at": "2025-09-21T07:29:41.057917Z",
"languages": [
"zh"
],
"visibility": "public",
"lock_visibility": false,
"default_text": "通过长期观察发现，珊瑚礁生态系统中的鱼类具有复杂的群体行为模式。它们利用色彩变化和特定的游动姿态来传递信息，这种精密的非语言交流系统展现了海洋生物的适应智慧。",
"like_count": 0,
"mark_count": 0,
"shared_count": 0,
"task_count": 0,
"unliked": false,
"liked": false,
"marked": false,
"author": {
"_id": "7ecad23df62a4174acd6a2a6cb5201ee",
"nickname": "Matthew Garcia",
"avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
}
}
}
success，此时音色创建任务的状态情况。
data，音乐任务的结果
_id，此时音色生成任务ID，后续是用此ID进行克隆声音的创作。title，音色的标题。image_url，音色的封面信息。description，音色的描述信息。train_mode，此时音色生成任务所采用的模式。tags，音色的风格。default_text，此时音色生成任务的声音文本信息。
可以看到我们得到了满意的音色信息，我们只需要根据结果中 data 的_id进行克隆声音任务即可。
另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
curl -X POST 'https://api.acedata.cloud/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
"title": "test",
"description": "test"
}'
异步回调
由于 Fish Voices Generation API生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。
整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成任务的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。
下面我们通过示例来了解下具体怎样操作。
首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：
将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34。
接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：
点击运行，可以发现会立即得到一个结果，如下：
{
"task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34 上观察到生成任务的结果，如图所示：
内容如下：
{
"success": true,
"task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
"trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
"data": {
"_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
"type": "tts",
"title": "test",
"description": "test",
"cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
"train_mode": "fast",
"state": "trained",
"tags": [],
"samples": [
{
"title": "Default Sample",
"text": "海豚通过回声定位系统在海洋中导航，这种精确的声波技术让它们能够探测周围环境，寻找食物和避开危险。这不仅展现了海洋生物的适应能力，也揭示了大自然的奇妙设计。",
"task_id": "68cdda24d26e4794bae177e20da740db",
"audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
}
],
"created_at": "2025-09-21T07:36:20.200865Z",
"updated_at": "2025-09-21T07:36:20.200353Z",
"languages": [
"zh"
],
"visibility": "public",
"lock_visibility": false,
"default_text": "海豚通过回声定位系统在海洋中导航，这种精确的声波技术让它们能够探测周围环境，寻找食物和避开危险。这不仅展现了海洋生物的适应能力，也揭示了大自然的奇妙设计。",
"like_count": 0,
"mark_count": 0,
"shared_count": 0,
"task_count": 0,
"unliked": false,
"liked": false,
"marked": false,
"author": {
"_id": "7ecad23df62a4174acd6a2a6cb5201ee",
"nickname": "Matthew Garcia",
"avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
}
}
}
task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。
错误处理
在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
400 token_mismatched：Bad request, possibly due to missing or invalid parameters.400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.401 invalid_token：Unauthorized, invalid or missing authorization token.429 too_many_requests：Too many requests, you have exceeded the rate limit.500 api_error：Internal server error, something went wrong on the server.
错误响应示例
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
