鱼音频生成 API 集成指南

在这篇文章中，我们将介绍如何集成鱼音频生成 API，该 API 能够通过输入提示词来克隆您的声音。这项技术的应用场景包括语音合成、自动化语音助手、以及任何需要个性化语音输出的应用。

环境准备

在使用鱼音频生成 API 之前，您需要先申请相应的服务。请确保您已注册并登录到 Ace Data Cloud 平台。

申请过程

首先，访问鱼音频生成 API 页面。进入页面后，点击"获取"按钮，如下图所示：

如果您尚未登录或注册，系统会自动引导您进行注册或登录。完成后，您将自动返回到当前页面。

首次申请时，您将获得免费的配额，允许您免费使用 API。

基本用法

了解基本用法后，您需要输入以下几个参数：

prompt：提示词
action：克隆操作
voice_id：声音 ID
model：模型名称

您需要传入一个字段 action，值为 generate，并输入模型 model，当前主要使用 fish-tts 模型，具体如下：

请求头部设置包括：

accept：您希望接收的响应结果格式，这里填入 application/json，表示 JSON 格式。
authorization：调用 API 的密钥，申请后可直接选择。

请求体需要设置如下字段：

model：用于克隆声音的模型，主要是 fish-tts。
action：本次声音克隆任务的操作。
prompt：需要克隆的提示词。
voice_id：用于克隆的声音 ID。
callback_url：接收回调结果的 URL。

完成设置后，右侧将生成相应的代码，如下图所示：

点击"尝试"按钮进行测试，结果如下：

json 复制代码

{
  "success": true,
  "task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
  "trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
  "data": [
    {
      "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
    }
  ]
}

返回的结果包含多个字段，具体描述如下：

success：表示声音克隆任务的状态。
data：声音克隆任务的结果
audio_url：此次声音克隆任务的音频链接。

我们可以看到，已经获得了满意的声音信息，只需根据 data 中的音乐链接地址获取克隆的声音。

如果您希望生成相应的集成代码，可以直接复制生成的代码，例如，CURL 代码如下：

shell 复制代码

curl -X POST 'https://api.acedata.cloud/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "speech",
  "prompt": "a white siamese cat",
  "model": "fish-tts",
  "voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'

异步回调

由于鱼音频生成 API 的生成时间相对较长，大约需要 1-2 分钟。如果 API 长时间未响应，HTTP 请求将保持连接开放，导致额外的系统资源消耗。因此，该 API 还支持异步回调。

总体过程为：当客户端发起请求时，指定一个额外的 callback_url 字段。API 将立即返回包含 task_id 字段信息的结果，表示当前任务 ID。当任务完成后，生成任务的结果将以 POST JSON 的形式发送到客户端指定的 callback_url，同时包含 task_id 字段，以便通过 ID 关联任务结果。

我们通过一个示例来具体理解该操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应将其替换为自己的 HTTP 服务器 URL。为了演示，我们使用公共 Webhook 示例网站 https://webhook.site/。打开该网站后，将获得一个 Webhook URL，如下图所示：

复制此 URL，它可以用作 Webhook。样例 URL 为 https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34。

接下来，我们可以在填写相应参数时设置 callback_url 字段为上述 Webhook URL，如下图所示：

点击运行后，您会立即收到结果，如下所示：

json 复制代码

{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}

片刻之后，您可以在 https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34 查看生成任务的结果，如下图所示：

内容如下：

json 复制代码

{
    "success": true,
    "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
    "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
    "data": [
        {
            "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
        }
    ]
}

我们可以看到，结果包含 task_id 字段，其他字段与上述描述相似，通过此字段可以关联任务。

错误处理

调用 API 时，如果发生错误，API 将返回相应的错误代码和消息。例如：

400 token_mismatched：错误请求，可能由于缺少或无效的参数。
400 api_not_implemented：错误请求，可能由于缺少或无效的参数。
401 invalid_token：未经授权，无效或缺少授权令牌。
429 too_many_requests：请求过多，您已超出速率限制。
500 api_error：内部服务器错误，服务器出现问题。

错误响应示例

json 复制代码

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

总结

通过本文，您已学习如何使用鱼音频生成 API 通过输入提示词克隆声音。希望本指南能帮助您更好地集成和使用该 API。如果您有任何疑问，请随时联系技术支持团队。

标签：#API集成 #语音合成 #AceDataCloud #技术教程 #开发者指南