Fish TTS API 接続説明

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

申請プロセス

Fish TTS API を使用するには、まず Ace Data Cloud コンソールで API トークンを取得し、保管してください。

まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、コンソールで共通残高をチャージできます。

📘 完全なドキュメント：Fish TTS API →

リクエストヘッダー

ヘッダー	必須	説明
`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 で作成するか、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 ドキュメントを参照してください。

例 1：最小リクエスト（`text` + `format=mp3`）

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

返却（実測）：

{
  "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 で取得できます）：

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"
  }'

返却（実測）：

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

例 3：スピード / 音量の調整（`prosody`）

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"
  }'

返却（実測）：

{
  "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 ビットレートを制御します：

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
  }'

返却（実測）：

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

例 5：PCM 生波形

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

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
  }'

返却（実測）：

{
  "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を含めます。

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"
  }'

即時返却（実測）：

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

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

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

また、Fish Tasks APIを使用してtask_idに基づいて結果をプルすることもできます。詳細はその文書を参照してください。

エラーハンドリング

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

エラー応答の例：

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

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

{
  "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とFish Model Getを併用してください。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

プロキシ

上級

申請プロセス

リクエストヘッダー

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

例 1：最小リクエスト（`text` + `format=mp3`）

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

例 3：スピード / 音量の調整（`prosody`）

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

例 5：PCM 生波形

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

エラーハンドリング

結論

​申請プロセス

​リクエストヘッダー

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

​例 1：最小リクエスト（text + format=mp3）

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

​例 3：スピード / 音量の調整（prosody）

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

​例 5：PCM 生波形

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

​エラーハンドリング

​結論

申請プロセス

リクエストヘッダー

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

例 1：最小リクエスト（`text` + `format=mp3`）

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

例 3：スピード / 音量の調整（`prosody`）

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

例 5：PCM 生波形

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

エラーハンドリング

結論