> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API Integrationsbeskrivning

> Fish voice generation API guide - Ace Data Cloud

Detta gränssnitt är baserat på [Fish Audio officiella TTS API](https://docs.fish.audio/text-to-speech/text-to-speech), med skillnader endast i autentiseringsmetod (användning av token från denna plattform) och asynkron callback (`callback_url`-utvidgning), begärningskroppens struktur är densamma som upstream. Adressen är `POST https://api.acedata.cloud/fish/tts`.

## Ansökningsprocess

För att använda Fish TTS API, börja med att gå till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token, som du kan spara för framtida bruk.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

Om du inte är inloggad eller registrerad kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan.

**En API-token räcker för att anropa alla tjänster på plattformen, det behövs ingen separat ansökan för varje tjänst.** Första ansökan ger en gratis kvot för att prova; om kvoten är otillräcklig kan du ladda på allmän balans i [konsolen](https://platform.acedata.cloud/console/coin).

> 📘 Fullständig dokumentation: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## Begärningshuvud

| Header          | Obligatorisk | Beskrivning                                                                                                                                                                                                                    |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authorization` | Ja           | `Bearer {token}`, där `{token}` är nyckeln som ansöktes på denna plattform.                                                                                                                                                    |
| `content-type`  | Ja           | `application/json`.                                                                                                                                                                                                            |
| `accept`        | Nej          | `application/json`.                                                                                                                                                                                                            |
| `model`         | Nej          | TTS-modell, valfri `s1`, `s2-pro` eller `s2.1-pro`, standard `s2-pro`. `s2.1-pro` är den senaste generationen, `s2-pro` har starkare uttryck; `s1` är mer stabil, lång text tenderar inte att avvika. Alla tre har samma pris. |

## Begärningskroppsfält

| Fält           | Typ                 | Obligatorisk | Beskrivning                                                                                                                                                                                        |
| -------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | Ja           | Texten som ska syntetiseras, en icke-tom sträng.                                                                                                                                                   |
| `format`       | string              | Nej          | Utdata ljudformat, valfri `mp3` (standard), `wav`, `pcm`. `wav` och `pcm` returnerar båda WAV-container. `opus` stöds inte, om det anges returneras direkt `400`.                                  |
| `reference_id` | string \| string\[] | Nej          | Klonad röst-ID (kan skapas av [Fish Model API](https://platform.acedata.cloud/documents/fish-model) eller hämtas i [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | Nej          | Inline referensprov, strukturen är densamma som upstream, varje post innehåller `audio` och `text`. Antingen `reference_id` eller `references` kan användas.                                       |
| `sample_rate`  | integer             | Nej          | Samplingsfrekvens, vanliga värden är `16000`, `22050`, `44100`. `format=mp3` har standard 44100.                                                                                                   |
| `mp3_bitrate`  | integer             | Nej          | MP3-bitrate, valfri `64`, `128`, `192`. Gäller endast `format=mp3`.                                                                                                                                |
| `prosody`      | object              | Nej          | Prosodiöverlagring, stöder `speed` (talhastighet, 1.0 är originalhastighet) och `volume` (volymförstärkning dB). Till exempel `{"speed":1.2,"volume":0}`.                                          |
| `chunk_length` | integer             | Nej          | Upstream-delning längd, standard beslutas av upstream.                                                                                                                                             |
| `temperature`  | number              | Nej          | Samplings temperatur, intervall cirka 0.0–1.0.                                                                                                                                                     |
| `top_p`        | number              | Nej          | top-p samplingsparameter.                                                                                                                                                                          |
| `latency`      | string              | Nej          | `normal` eller `balanced`, standard är automatiskt `normal` (om en tom sträng skickas kommer upstream att avvisa).                                                                                 |
| `normalize`    | boolean             | Nej          | Om texten ska normaliseras.                                                                                                                                                                        |
| `callback_url` | string              | Nej          | Asynkron callback-adress, se nedan för "Asynkron callback". **Detta är en utvidgning av det officiella gränssnittet**.                                                                             |

> Fältnamn är helt identiska med upstream. Förutom `callback_url` hänvisar övriga fält till [Fish officiella TTS-dokumentation](https://docs.fish.audio/text-to-speech/text-to-speech).

## Exempel 1: Minsta begäran (`text` + `format=mp3`)

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

Svar (testat):

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

`audio_url` pekar på plattformens CDN, kan direkt GET-ladda ner eller spelas i `<audio>`. Länken är långvarig, men det rekommenderas fortfarande att spara en kopia i din egen lagring.

## Exempel 2: Använda klonad röst `reference_id`

Nedan används en offentlig spansktalande röst på Fish-plattformen (`_id` kan hämtas via [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
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"
  }'
```

Svar (testat):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}
```

## Exempel 3: Justera talhastighet / volym (`prosody`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'
```

Svar (testat):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}
```

`speed` större än 1 ökar hastigheten, mindre än 1 sänker den; `volume` enhet dB, 0 betyder oförändrad, positiva värden ökar, negativa värden minskar.

## Exempel 4: Byta modell + kontrollera bitrate

Genom HTTP-huvudet `model: s1` byter vi till den stabila modellen, lägg till `mp3_bitrate: 128` i begärningskroppen för att kontrollera MP3-bitraten:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "hög bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Återkomst (verklig mätning):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}
```

## Exempel 5: PCM råvågform

Behöver göra realtidskoppling i webbläsaren, eller göra efterbehandling (mixning, hastighetsändring) på klienten, rekommenderas att använda `pcm`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "hej",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

Återkomst (verklig mätning):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}
```

> Länkens filändelse följer begäran i `format`: `mp3` ger `.mp3`, `wav` och `pcm` ger `.wav` (WAV-container, 16 bit PCM).

## Asynkron återkoppling (`callback_url`)

Långa texter kan ta flera sekunder till flera minuter att sammanfoga, om anslutningen bryts behöver den försöka igen. När `callback_url` skickas i begäran kommer gränssnittet omedelbart att returnera `{task_id, started_at}`, när den verkliga uppgiften är klar kommer det kompletta resultatet att återkopplas till den URL:en i POST JSON-format, med samma `task_id` i begäran.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Idag är vädret verkligen bra, låt oss gå ut och ta en promenad.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Omedelbar återkomst (verklig mätning):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

Senare kommer `callback_url` att ta emot något som:

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}
```

Det går också att använda [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) för att aktivt hämta resultatet med `task_id`, se den dokumentationen för mer information.

## Felhantering

* `400 token_mismatched`: Begärningsparametrar saknas eller är ogiltiga (vanligast är att `text` är tom, eller att `format` har ett värde utöver `mp3`/`wav`/`pcm`).
* `401 invalid_token`: Autentiseringstoken finns inte eller är ogiltig.
* `429 too_many_requests`: Utlöst konto hastighetsbegränsning.
* `500 api_error`: Intern serverfel.

Exempel på felrespons:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "hämtning misslyckades"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Parametervalideringsfel kommer att placera den ursprungliga pydantic-felmeddelandet från upstream i `message`-fältet, vilket underlättar att lokalisera vilket fält som är ogiltigt, till exempel:

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Inmatning bör vara 'pcm' eller 'mp3'\",\"input\":\"wav\"}]"
}
```

## Slutsats

Den minimi kostnaden för att integrera Fish TTS är: att i den befintliga koden som anropar `api.fish.audio/v1/tts` byta autentisering till plattformens token och i begäran **uttryckligen inkludera** `format: "mp3"`. För långa textscenarier rekommenderas att använda `callback_url` för asynkron återkoppling; för att upptäcka klonade röster `reference_id`, vänligen kombinera med [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) och [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).