> ## 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 接続説明

> Fish voice generation API guide - Ace Data Cloud

本インターフェースは [Fish Audio 公式 TTS API](https://docs.fish.audio/text-to-speech/text-to-speech) に基づいており、認証方式（このプラットフォームのトークンを使用）と非同期コールバック（`callback_url` 拡張）に違いがあります。リクエストボディの構造は上流と一致しています。アドレスは `POST https://api.acedata.cloud/fish/tts` です。

## 申請プロセス

Fish TTS API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。

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

まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[Fish TTS API →](https://platform.acedata.cloud/services/fish)

## リクエストヘッダー

| ヘッダー            | 必須  | 説明                                                                                                                            |
| --------------- | --- | ----------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | はい  | `Bearer {token}`、`{token}` はこのプラットフォームで申請したキーです。                                                                              |
| `content-type`  | はい  | `application/json`。                                                                                                           |
| `accept`        | いいえ | `application/json`。                                                                                                           |
| `model`         | いいえ | TTS モデル、選択肢は `s1`、`s2-pro` または `s2.1-pro`、デフォルトは `s2-pro`。`s2.1-pro` は最新世代、`s2-pro` は表現力が強い；`s1` はより安定しており、長文がずれにくい。3つは同価格です。 |

## リクエストボディフィールド

| フィールド          | タイプ                 | 必須  | 説明                                                                                                                                                                             |
| -------------- | ------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`         | string              | はい  | 合成するテキスト、空でない文字列。                                                                                                                                                              |
| `format`       | string              | いいえ | 出力音声フォーマット、選択肢は `mp3`（デフォルト）、`wav`、`pcm`。`wav` と `pcm` はどちらも WAV コンテナで返されます。`opus` はサポートされておらず、入力すると直接 `400` が返されます。                                                           |
| `reference_id` | string \| string\[] | いいえ | クローン音色 ID（[Fish Model API](https://platform.acedata.cloud/documents/fish-model) で作成するか、[Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) で取得できます）。 |
| `references`   | object\[]           | いいえ | インライン参照サンプル、構造は上流と一致し、各項目には `audio` と `text` が含まれます。`reference_id` と二者択一です。                                                                                                    |
| `sample_rate`  | integer             | いいえ | サンプリングレート、一般的には `16000`、`22050`、`44100`。`format=mp3` の場合はデフォルトで 44100。                                                                                                         |
| `mp3_bitrate`  | integer             | いいえ | MP3 ビットレート、選択肢は `64`、`128`、`192`。`format=mp3` の場合のみ有効です。                                                                                                                       |
| `prosody`      | object              | いいえ | 韻律オーバーライド、`speed`（スピード、1.0 が元の速度）と `volume`（音量ゲイン dB）をサポートします。例： `{"speed":1.2,"volume":0}`。                                                                                   |
| `chunk_length` | integer             | いいえ | 上流のチャンク長、デフォルトは上流が決定します。                                                                                                                                                       |
| `temperature`  | number              | いいえ | サンプリング温度、範囲は約 0.0–1.0。                                                                                                                                                         |
| `top_p`        | number              | いいえ | top-p サンプリングパラメータ。                                                                                                                                                             |
| `latency`      | string              | いいえ | `normal` または `balanced`、デフォルトはこのインターフェースが自動的に `normal` を補完します（空文字列を直接渡すと上流が拒否します）。                                                                                             |
| `normalize`    | boolean             | いいえ | テキストを正規化するかどうか。                                                                                                                                                                |
| `callback_url` | string              | いいえ | 非同期コールバックアドレス、詳細は下記「非同期コールバック」を参照してください。**これは公式インターフェースに対する拡張です。**                                                                                                             |

> フィールド名は上流と完全に一致しています。`callback_url` を除き、他のフィールドの意味と値は [Fish 公式 TTS ドキュメント](https://docs.fish.audio/text-to-speech/text-to-speech) を参照してください。

## 例 1：最小リクエスト（`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"
  }'
```

返却（実測）：

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

`audio_url` はこのプラットフォームの CDN を指し、直接 GET でダウンロードするか `<audio>` で再生できます。リンクは長期間使用可能ですが、自分のストレージにもコピーを残すことをお勧めします。

## 例 2：クローン音色 `reference_id` の使用

以下は Fish プラットフォーム上の公開されたスペイン語音色を使用しています（`_id` は [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"
  }'
```

返却（実測）：

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

## 例 3：スピード / 音量の調整（`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"
  }'
```

返却（実測）：

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

`speed` が 1 より大きいと速くなり、1 より小さいと遅くなります；`volume` の単位は dB で、0 は変わらず、正数は増加、負数は減少を示します。

## 例 4：モデルの切り替え + ビットレートの制御

HTTP ヘッダー `model: s1` で安定型モデルに切り替え、リクエストボディに `mp3_bitrate: 128` を追加して MP3 ビットレートを制御します：

```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": "高ビットレートのmp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

返却（実測）：

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

## 例 5：PCM 生波形

ブラウザでリアルタイムに接続したり、クライアントで後処理（ミキシング、速度変更）を行うシーンでは、`pcm`の使用を推奨します：

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

返却（実測）：

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

> リンクの拡張子はリクエスト内の`format`に従います：`mp3`で`.mp3`を取得し、`wav`と`pcm`で`.wav`を取得します（WAVコンテナ、16ビットPCM）。

## 非同期コールバック（`callback_url`）

長いテキストの合成には数秒から数十秒かかることがあり、接続が中断された場合は再試行が必要です。リクエストボディに`callback_url`を渡すと、インターフェースはすぐに`{task_id, started_at}`を返します。上流で実際に完了した際に、完全な結果をPOST JSON形式でそのURLにコールバックし、リクエストボディには同じ`task_id`を含めます。

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今日は天気が良いので、一緒に散歩に行きましょう。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

即時返却（実測）：

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

後で`callback_url`は次のような形で受け取ります：

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

また、[Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks)を使用して`task_id`に基づいて結果をプルすることもできます。詳細はその文書を参照してください。

## エラーハンドリング

* `400 token_mismatched`：リクエストパラメータが欠落または不正（最も一般的なのは`text`が空であるか、`format`に`mp3`/`wav`/`pcm`以外の値が渡された場合）。
* `401 invalid_token`：認証トークンが存在しないか無効。
* `429 too_many_requests`：アカウントのレート制限が発動。
* `500 api_error`：サーバー内部エラー。

エラー応答の例：

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

パラメータ検証エラーは、上流のpydanticのエラーメッセージを`message`フィールドに配置し、どのフィールドが不正であるかを特定しやすくします。例えば：

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}
```

## 結論

Fish TTSを接続する最小コストは、既存の`api.fish.audio/v1/tts`を呼び出すコードで認証をこのプラットフォームのトークンに置き換え、リクエストボディに**明示的に**`format: "mp3"`を含めることです。長文シーンでは`callback_url`の非同期コールバックを使用することをお勧めします；クローン音色`reference_id`の発見については、[Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)と[Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get)を併用してください。