A Practical Guide to Adding Text-to-Speech with the Fish TTS API

A Practical Guide to Adding Text-to-Speech with the Fish TTS API

If your app turns written content into lessons, onboarding videos, support replies, or accessibility audio, the hard part is rarely “call a TTS endpoint.” The hard part is choosing the right voice source, keeping audio formats predictable, and handling longer syntheses without blocking your product flow.

This guide walks through the Fish TTS API on Ace Data Cloud as a practical integration path. We will keep the scope narrow: one endpoint, the fields documented for it, and a few patterns you can adapt in a real builder workflow.

What you can do

The Fish TTS endpoint is POST https://api.acedata.cloud/fish/tts. It supports plain text-to-speech, reusable saved voices through reference_id, one-time instant voice cloning through references, output format control, prosody overrides, model selection through a request header, and asynchronous delivery through callback_url.

At a high level, you send JSON containing at least text. The response returns an audio_url for completed synchronous requests. For asynchronous requests, the first response contains a task_id and started_at, and the final result is posted to your callback URL.

How it works

Authentication is a bearer token in the authorization header. The request body is JSON, so you should also send content-type: application/json. The optional model header can be one of s1, s2-pro, or s2.1-pro. The documented default is s2-pro; s1 is described as more stable for long text, while s2-pro is expressive.

The most important body fields are:

  • text: required non-empty string to synthesize.
  • format: optional output format, with mp3 as the default. The docs list mp3, wav, and pcm; opus is not supported.
  • reference_id: saved or public voice model ID, either a string or string array. It cannot be used at the same time as references.
  • references: one-time voice cloning sample. The documented shape is an array with one object containing audio and text.
  • prosody: optional object supporting speed and volume.
  • callback_url: optional URL for asynchronous completion callbacks.

Start with the smallest possible request

The minimal integration should be boring. Make one call, confirm you can download or play the returned file, then add voice control later.

curl -X POST 'https://api.acedata.cloud/fish/tts'   -H 'authorization: Bearer {token}'   -H 'content-type: application/json'   -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'

A successful synchronous response contains an audio_url:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

In a web app, treat that URL as a generated asset: you can play it in an <audio> element or fetch it for storage in your own media bucket.

Use a reusable voice when consistency matters

If you are building a product tour, language-learning flow, or narrated documentation, you usually want the same voice across many clips. That is the reference_id path. A reference_id points to a saved or public voice model, and the same ID can be reused across requests.

curl -X POST 'https://api.acedata.cloud/fish/tts'   -H 'authorization: Bearer {token}'   -H 'content-type: application/json'   -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'

Use this mode when voice identity is part of the user experience. Keep the ID in configuration rather than scattering it across business logic, because you may want to rotate voices per locale, product, or narrator.

Use one-time references for temporary voice cloning

For cases where you do not want to create a long-term reusable model, the endpoint also supports references. The documented constraints matter: the reference audio must be a public HTTPS MP3 or WAV URL, not a Base64 string, data URI, MessagePack payload, or credentialed URL. The reference object needs both audio and the accurate transcript in text.

curl -X POST 'https://api.acedata.cloud/fish/tts'   -H 'authorization: Bearer {token}'   -H 'content-type: application/json'   -H 'model: s2-pro'   -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

This is useful for workflows where the voice changes per job: a creator uploads a sample, a support team generates a single localized message, or an internal tool needs a temporary narration style.

Tune delivery for product workflows

For short clips, synchronous calls are simple. For longer text, prefer callback_url. The first response confirms a task:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

Later, your callback receives the completed payload with the same task_id and an audio_url. That maps cleanly to a job table: store task_id, mark the row as processing, and update it when the webhook arrives.

You can also tune audio characteristics directly in the request. For faster speech, use prosody.speed above 1; for slower speech, use a value below 1. prosody.volume is a dB adjustment where 0 means no change. For MP3 output, mp3_bitrate accepts documented values such as 64, 128, and 192. For downstream processing, pcm with sample_rate such as 16000 returns a WAV container suitable for later mixing or stitching.

Handle errors deliberately

The docs call out common failure classes: 400 token_mismatched for missing or invalid parameters, 401 invalid_token for authentication problems, 429 too_many_requests for rate limits, and 500 api_error for internal failures. In practice, log the response body and any trace ID, avoid retrying invalid input, and only retry transient failures with backoff.

Where to go next

A good first version is: send text, request format: "mp3", save the returned audio_url, and add callback_url when your text length or user experience demands background processing. Once that path is stable, add reference_id for reusable voices or references for one-off voice samples.

For the complete field list and the original examples, read the Fish TTS API Integration Guide.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more