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 コンソール にアクセスして API Token を取得し、控えておいてください。

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

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

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

​

リクエストヘッダー

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 で作成するか、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）

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://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 で検索して取得できます）：

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

​

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

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

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": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

実測成功レスポンス：

{
  "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）

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://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 ビットレートを制御します。

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

レスポンス（実測）：

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

​

例 6：PCM 生波形

ブラウザ内でリアルタイム結合を行う、またはクライアント側で後続処理（ミキシング、速度変更）を行うシナリオでは、pcm の使用を推奨します。

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

レスポンス（実測）：

{
  "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 は含まれません。

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

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

​

エラー処理

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

エラーレスポンスの例：

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

パラメータ検証エラーでは、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 を呼び出すコード内で認証を本プラットフォームの token に置き換え、リクエストボディに明示的に format: "mp3" を含めることです。長文のシナリオでは callback_url による非同期コールバックの使用を推奨します。クローン音声の reference_id を見つけるには、Fish Model Query と Fish Model Get を併用してください。