fish-audio

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fish Audio — Text-to-Speech

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

## First-time setup

1. Already installed from skills.sh? Continue at step 2. For a coding agent, install with `npx skills add acedatacloud/skills --skill fish-audio --yes` ([installation and first run](https://github.com/AceDataCloud/Skills#first-run-from-skillssh)). For OpenClaw, use `clawhub install @acedatacloud/fish-audio` and check that the ClawHub publisher is **@acedatacloud**.
2. Sign in at [AceDataCloud → Applications](https://platform.acedata.cloud/console/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. For a coding agent or direct command, export `ACEDATACLOUD_API_TOKEN="your_api_key_here"` in the environment of the process that runs the Skill; project `.env` loading is agent-specific. For OpenClaw, put `ACEDATACLOUD_API_TOKEN=your_api_key_here` in `~/.openclaw/.env` on the Gateway host, then restart the Gateway and start a new session. 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](https://github.com/AceDataCloud/Skills#first-run-with-clawhub-and-openclaw) · [Token details](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md)

If you came from skills.sh, use [Applications for this first run](https://platform.acedata.cloud/console/applications?utm_source=skills_sh&utm_medium=referral&utm_campaign=evergreen&utm_content=fish_audio_first_run). Check the current price before generating audio.

## 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

| Endpoint | Purpose |
|----------|---------|
| `POST /fish/tts` | Text-to-speech generation |
| `POST /fish/model` | Create a persistent public voice model from an audio URL |
| `GET /fish/model` | Browse/search public voices or list voices created through this platform with `self=true` |
| `GET /fish/model/{id}` | Fetch one reference voice by ID |
| `POST /fish/tasks` | Poll 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](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/async-tasks.md) and query `POST /fish/tasks` with `{"id":"..."}`.

### 5. Create a persistent public voice model

Only use audio the user has permission to clone and publish. Before submitting, obtain explicit confirmation that the voice will be saved publicly long-term and other users may search for and use it. Do not proceed if a private saved voice is required: `visibility` does not change publication, even when set to `private` or `unlist`. Omit it from requests. For a temporary reference without a saved model, use the one-shot workflow above.

Replace `HTTPS_REFERENCE_AUDIO_URL` with a publicly downloadable audio URL, preferably ending in `.mp3` or `.wav`:

```json
POST /fish/model
{
  "title": "My authorized narration voice",
  "voices": "HTTPS_REFERENCE_AUDIO_URL"
}

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills