Fish Audio — Text-to-Speech#

Generate narration / voiceover through AceDataCloud's Fish Audio API.

First-time setup#

1. Install the official Skill with clawhub install @acedatacloud/fish-audio. Check that the ClawHub publisher is @acedatacloud.
2. Sign in at AceDataCloud → Applications, open General application, and check Fish Audio access, balance, and current pricing. Copy its API key, or select Manage Keys → Create for a separate key. Copy the key value without Bearer ; a platform-... management token is not a service API key.
3. If you enable Allowed APIs restrictions, include /fish/tts (and /fish/tasks for asynchronous TTS). Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put ACEDATACLOUD_API_TOKEN=your_api_key_here in ~/.openclaw/.env, then restart the Gateway and start a new session. For a direct terminal test, run export ACEDATACLOUD_API_TOKEN="your_api_key_here" in that shell. Never put the key in a prompt or commit an .env file.
5. Run the Quick Start below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress.

Illustrated key setup, first run, and troubleshooting · Token details

Quick Start#

bash

curl -X POST https://api.acedata.cloud/fish/tts \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "model: s2-pro" \
  -d '{"text":"你好，欢迎使用 AceData Cloud。","reference_id":"d7900c21663f485ab63ebdb7e5905036","format":"mp3"}'

Synchronous responses return a direct audio URL:

json

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

Endpoints#

EndpointPurposePOST /fish/ttsText-to-speech generationGET /fish/modelBrowse/search public Fish reference voicesGET /fish/model/{id}Fetch one reference voice by IDPOST /fish/tasksPoll async TTS jobs when async: true

Workflows#

1. Find a reference voice#

bash

curl "https://api.acedata.cloud/fish/model?page_size=10&page_number=1&title=Marcus" \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

The response includes items[] with public voice metadata such as _id, title, languages, tags, visibility, and state. Use an item _id as reference_id in TTS requests.

2. Text-to-Speech#

json

POST /fish/tts
Headers:
  model: s2-pro

{
  "text": "Your narration text.",
  "reference_id": "d7900c21663f485ab63ebdb7e5905036",
  "format": "mp3"
}

3. One-shot voice cloning#

Use a temporary reference voice without creating a persistent model:

json

POST /fish/tts
Headers:
  model: s2-pro

{
  "text": "New speech in the referenced voice.",
  "format": "mp3",
  "references": [{
    "audio": "https://cdn.acedata.cloud/reference.mp3",
    "text": "The exact words spoken in the reference audio."
  }]
}

audio must be a public HTTPS MP3/WAV URL and text must be the exact transcript. Use one reference lasting 10–270 seconds. Do not combine references with reference_id; use reference_id when the same saved/public voice will be reused. Raw bytes, Base64, data URIs, and MessagePack are not accepted by the AceDataCloud endpoint.

4. Async TTS#

json

POST /fish/tts
Headers:
  model: s1

{
  "text": "Longer narration for background processing.",
  "callback_url": "https://your-domain.example/fish-webhook"
}

Use an actual public webhook that you operate; replace the example URL. If you do not have one, use the synchronous Quick Start above. After an asynchronous submission returns a task ID, see async task polling and query POST /fish/tasks with {"id":"..."}.

Parameters — /fish/tts#

Header#

ParameterValuesDescriptionmodel``"s1", "s2-pro", "s2.1-pro"Fish TTS engine selection

JSON body#

ParameterType / ValuesDescriptiontextstringText to synthesize (required)reference_idstringPublic/reference voice ID from GET /fish/model``format``"mp3", "wav", "pcm"Output formatsample_rateintegerOptional output sample ratemp3_bitrate``64, 128, 192MP3 bitratelatency``"normal", "balanced"TTS latency modechunk_length / min_chunk_lengthintegerChunking controlstemperature, top_p, repetition_penaltynumberSampling controlsmax_new_tokensintegerMaximum generated tokensnormalizebooleanNormalize generated audioprosodyobjectProsody tuningreferencesarrayOne {audio, text} object for a one-shot voice clone; mutually exclusive with reference_id``callback_urlstringAsync callback URLasyncbooleanRun asynchronously and poll /fish/tasks

Gotchas#

• The documented TTS endpoint is POST /fish/tts — not /fish/audios.
• Choose the Fish engine with the model request header, not a JSON model field.
• Use reference_id from GET /fish/model — not voice_id.
• Use references for a one-shot clone that is not saved as a model.
• Billing is based on the target text UTF-8 byte count; the reference audio does not add a separate clone fee.
• Synchronous requests return audio_url directly; async jobs should be polled via /fish/tasks.