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

本インターフェースはテキスト読み上げ、保存済み音声の呼び出し、およびワンタイムの即時音声クローンを提供します。URL は `POST https://api.acedata.cloud/fish/tts` です。

## 申請プロセス

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

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

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

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

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

## リクエストヘッダー

| Header | 必須 | 説明 |
| - | - | - |
| `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` と同時に使用することはできません。 |
| `references` | object\[] | いいえ | ワンタイムの即時音声クローン。`{audio, text}` サンプルを 1 つだけサポートします。`audio` は公開 HTTPS MP3/WAV URL、`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 | いいえ | 非同期コールバック URL。詳細は以下の「非同期コールバック」を参照してください。**これは公式インターフェースに対する拡張です**。 |

> ワンタイムクローンは HTTPS 音声 URL のみを受け付け、MessagePack、Base64、data URI、または認証情報付き URL は受け付けません。参照音声は 10～270 秒を推奨します。Studio ではより保守的な 10～60 秒の範囲を使用します。

## 例 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://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}
```

`audio_url` は本プラットフォームの CDN を指しており、直接 GET でダウンロードするか、`<audio>` 内で再生できます。最終的な成功レスポンスではトップレベルの `cost` も返され、その中の `amount` は今回実際に差し引かれた Credits です。アカウント割引がある場合、`list_amount` は割引前のクレジットを表します。リンクは長期間利用可能ですが、自身のストレージにもコピーを残しておくことを推奨します。

## 例 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://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}
```

## 例 3：ワンタイムの即時音声クローン（`references`）

参照音声を公開 HTTPS アドレスに配置し、実際に話された正確な原文を提供します。この音声は今回の合成にのみ使用され、長期モデルは作成されません。

```shell theme={null}
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://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'
```

実測成功レスポンス：

```json theme={null}
{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}
```

| 方式 | ライフサイクル | 適用シナリオ |
| - | - | - |
| `references` | 今回の TTS リクエストのみ | 一時的な使用または毎回音声が異なる場合 |
| `reference_id` | 繰り返し使用可能 | 共通の音声または `/fish/model` で作成した長期的な音声 |

## 例 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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}
```

`speed` は 1 より大きいと速くなり、1 より小さいと遅くなります。`volume` の単位は dB で、0 は変更なし、正数は増幅、負数は減衰を表します。

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

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": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

レスポンス（実測）：

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

## 例 6：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": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

レスポンス（実測）：

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

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

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

長文の一回の合成には十数秒から数十秒かかる場合があり、接続が中断された場合は再試行が必要です。リクエストボディで `callback_url` を渡すと、インターフェースは直ちに `{task_id, started_at}` を返します。上流処理が実際に完了した際、完全な結果が POST JSON 形式でその URL にコールバックされます。リクエストボディには同じ `task_id` と今回の最終課金額であるトップレベルの `cost` が含まれます。初期タスク確認時点では合成がまだ完了していないため、`cost` は含まれません。

```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://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}
```

[Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) を使用して、`task_id` で結果を能動的に取得することもできます。終端状態のレコードにある `response.cost` は、コールバック内の `cost` と一致します。詳細は当該ドキュメントを参照してください。

## エラー処理

* `400 token_mismatched`：リクエストパラメータが不足している、または不正です（最も多いのは `text` が空、または `format` に `mp3`/`wav`/`pcm` 以外の値を渡した場合です）。
* `401 invalid_token`：認証 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"
}
```

パラメータ検証エラーでは、`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` を呼び出すコード内で認証を本プラットフォームの token に置き換え、リクエストボディに**明示的に** `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) を併用してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.