用 Ace Data Cloud 快速接入 Fish TTS：把文本转成自然语音

最近很多开发者在做 AI 语音相关的产品：有的是给知识库加语音播报，有的是做短视频旁白，有的是做客服机器人、播客生成、学习工具，甚至只是想把一段文本快速转成自然一些的中文音频。

如果只是体验模型，直接用网页工具就够了；但如果要把 TTS 能力接进自己的产品，真正麻烦的通常不是“模型能不能说话”，而是这些工程问题：

• 鉴权方式是否稳定，能不能和现有后端统一管理；
• 请求参数是否清晰，能不能直接用 curl、Python、Node.js 调起来；
• 长文本生成耗时较长时，是否支持异步回调；
• 多个 AI 能力是否可以用同一套 Token、余额和用量统计；
• 后续要接入图像、视频、音乐、语音等能力时，是否不用每个平台注册一遍。

这也是 Ace Data Cloud 想解决的问题：把不同 AI 服务封装成统一、可直接对接的 API，同时保留上游接口的核心字段，让开发者少做很多胶水工作。

这篇文章以 Fish TTS 为例，记录一下如何通过 Ace Data Cloud 接入文本转语音能力。

官方文档可以直接看这里：

platform.acedata.cloud/documents/f…

为什么选 Fish TTS？

Fish TTS 是一个比较适合产品化场景的语音生成能力。相比单纯的“念一段文本”，它更常见的用法包括：

• 给文章、课程、播客脚本生成自然语音；
• 为短视频批量生成旁白；
• 用参考音色生成更一致的品牌声音；
• 在 Agent、客服、陪伴类应用里做语音输出；
• 把现有内容库转成音频内容，提高消费效率。

Ace Data Cloud 的 Fish TTS API 重点不是重新设计一套完全不同的接口，而是尽量兼容 Fish Audio 官方 OpenAPI。也就是说，如果你之前已经在调用官方的 https://api.fish.audio/v1/tts，迁移到 Ace Data Cloud 时，主要变化是：

• 请求地址改成 https://api.acedata.cloud/fish/tts；
• 鉴权改成 Ace Data Cloud 平台的 API Token；
• 请求体结构基本保持一致；
• 额外可以使用平台扩展的异步 callback 能力。

这点对工程迁移很重要，因为很多团队不想为了换一个接入入口，重写一遍业务参数。

Ace Data Cloud 的接入特点

1. 一个 Token 访问多个服务

在 Ace Data Cloud 控制台可以创建 API Token：

platform.acedata.cloud/console/app…

这个 Token 不只用于 Fish TTS，也可以用于平台上的其他 API 服务。对后端来说，这意味着你可以把 AI 能力接入方式统一起来，而不是在代码里维护一堆不同平台的 Key、余额、鉴权逻辑。

2. 统一余额和用量管理

新账号会有一定的免费额度，后续可以在控制台统一充值和查看用量：

platform.acedata.cloud/console/coi…

这对团队内部管理也比较方便：开发、测试、线上环境可以按项目拆 Token，也可以通过平台看整体消耗。

3. 尽量兼容上游接口

Ace Data Cloud 的 Fish TTS API 保留了官方 API 的主要请求字段，比如：

• text：要转换成语音的文本；
• reference_id：参考音色 ID；
• references：参考音频相关配置；
• prosody：韵律相关配置；
• format：输出格式；
• sample_rate：采样率；
• mp3_bitrate：MP3 比特率；
• chunk_length：文本切分长度；
• temperature、top_p：生成参数。

这意味着你可以把 Ace Data Cloud 看成一个更统一的接入层，而不是另一个需要重新学习的封闭 API。

最小调用示例

最简单的 TTS 请求只需要传入 text 字段。

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'

这里有几个点值得注意：

• authorization: Bearer {token} 使用的是 Ace Data Cloud 控制台里的 API Token；
• model 放在 HTTP Header 里，可选 s1 或 s2-pro；
• 如果不指定模型，默认使用 s2-pro；
• 请求体仍然保持 Fish TTS 的字段风格。

成功后会返回音频地址：

{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}

拿到 audio_url 后，你可以直接播放、下载，或者存到自己的对象存储里。

使用参考音色

如果你已经有可用的参考音色 ID，可以在请求体里加入 reference_id。

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'

这个能力适合需要固定声音风格的产品，比如课程旁白、品牌播报、AI 主播、客服机器人等。

长文本推荐使用异步回调

TTS 生成有一个典型问题：短文本很快，但长文本可能需要等待更久。如果后端一直保持 HTTP 长连接，资源占用和失败重试都会变复杂。

Ace Data Cloud 在兼容官方字段的基础上，额外扩展了 callback_url。

当请求体里带上 callback_url 时，API 会先返回一个 task_id，等生成完成后，再把最终结果 POST 到你的回调地址。

请求示例：

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://example.com/webhook/fish-tts"
  }'

接口会立即返回：

{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}

生成完成后，你的 callback_url 会收到类似这样的 JSON：

{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}

这样后端就可以把 TTS 任务当成异步任务处理：提交任务、保存 task_id、等待回调、更新业务状态。

一个简单的 Python 封装

实际项目里可以简单封装一下：

import requests

API_TOKEN = "your_acedata_token"


def create_tts(text: str, callback_url: str | None = None):
    url = "https://api.acedata.cloud/fish/tts"
    headers = {
        "accept": "application/json",
        "authorization": f"Bearer {API_TOKEN}",
        "content-type": "application/json",
        "model": "s2-pro",
    }
    payload = {
        "text": text,
        "format": "mp3",
        "sample_rate": 44100,
    }
    if callback_url:
        payload["callback_url"] = callback_url

    resp = requests.post(url, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    result = create_tts(
        "这是一段通过 Ace Data Cloud Fish TTS API 生成的中文语音。",
        callback_url="https://example.com/webhook/fish-tts",
    )
    print(result)

如果是短文本，可以不传 callback_url，直接拿 audio_url。如果是长文本，建议走异步流程。

错误处理建议

文档里提到，接口会保留 Fish 官方的 HTTP 状态码，同时使用 Ace Data Cloud 平台统一的错误响应格式。

常见错误包括：

• 400 token_mismatched：请求参数或 Token 不匹配；
• 400 api_not_implemented：接口或参数不支持；
• 401 invalid_token：Token 无效或没有传鉴权；
• 429 too_many_requests：请求过于频繁；
• 500 api_error：上游或平台内部错误。

错误响应示例：

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

这里的 trace_id 很有用，线上排查问题时可以记录下来，方便定位一次具体请求。

适合哪些场景？

我觉得 Fish TTS 这类 API 适合下面几类开发者：

1. 内容工具开发者：把文章、笔记、课程脚本转成音频；
2. 短视频工具开发者：自动生成旁白，再进入剪辑流程；
3. AI Agent 开发者：把文本回复转成语音输出；
4. 教育产品开发者：生成听力、跟读、讲解音频；
5. 企业内部系统：把公告、报告、客服回复转成语音。

如果后续还要接入图像生成、视频生成、音乐生成、语音生成等能力，用 Ace Data Cloud 这种统一 API 平台会更省事：同一套 Token、同一套余额、同一套请求风格，减少在多个供应商之间切换的工程成本。

小结

通过 Ace Data Cloud 接入 Fish TTS，核心优势不是“多包一层 API”，而是把产品化接入里常见的鉴权、余额、用量、异步任务、错误格式等问题统一起来。

对于开发者来说，最直接的体验是：

• 请求地址清晰：https://api.acedata.cloud/fish/tts；
• 使用 Bearer Token 鉴权；
• 兼容 Fish Audio 官方 OpenAPI 的主要字段；
• 支持 callback_url 异步回调；
• 可以和 Ace Data Cloud 上其他 AI 能力共用一套平台能力。

如果你正在做 AI 语音、短视频旁白、文章转音频或 Agent 语音输出，可以从这个接口开始试一下。

文档入口：

platform.acedata.cloud/documents/f…

控制台入口：

platform.acedata.cloud/console/app…