非同期ジョブ

非同期 TTS ジョブは、長いテキスト、バッチ生成、Webhook スタイルのワークフロー、およびオーディオの処理中にユーザーがページから離れることができる UI フローに使用します。

ジョブの作成

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

＃＃＃リクエスト

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1,
  "pitch": 0,
  "language": "auto",
  "emotion": "neutral",
  "instruction": "Speak naturally",
  "textNormalization": true
}

テキストハッシュ、要求された音声、返されたタスク ID をデータベースに保存します。作成後にワーカーがクラッシュした場合は、2 番目のジョブを作成するよりもタスク ID によるポーリングの方が安全です。

この例では、パブリックシステムテスト音声 00a1b221-6137-4b73-ad62-b0cbce134167 を使用します。接続を確認した後、希望の音声 ID に置き換えてください。

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'

＃＃＃応答

作成エンドポイントは 202 Accepted を返します。ポーリングを開始する前に task.id を保存してください。

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

仕事を得る

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

ステータス値は pending、processing、success、partial_fail、fail です。

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

task.segments[].playbackUrl にも同じヘッダーが必要です。ダウンロードを復旧するために別のジョブを作成しないでください。

失われたタスク ID の復元

作成リクエストがサーバーに到達したものの、クライアントが 202 Accepted を受信できなかった場合は、まず最近のジョブを一覧表示します。

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

結果は作成日時の新しい順です。createdAt、textFingerprint、voiceId、engineModelId を使用してローカルのリクエストと照合できます。page、limit（最大 100）、status、ISO 8601 形式の createdAfter を指定できます。一覧にはテキストのプレビューのみが含まれ、全文は返されません。taskId を復元したら元のジョブをポーリングしてください。一覧取得では API クォータを消費しません。

請求とクレジット

サーバーはジョブを受け付けた時点で creditsUsed を 1 回だけ予約します。ポーリング、ダウンロード、同じ音声の再ダウンロードでは追加課金されません。事前課金済みのジョブが失敗した場合は、冪等な返金処理でクレジットが戻されます。

バッチの場合は、多数のタスクを追加する前に、側で同時実行性を調整し、プロファイルを確認してください。クレジット不足のために 1 つのタスクが失敗した場合は、アカウント所有者が残高を解決するまでバッチの rest を一時停止します。

エラー

ステータス	意味	アクション
`400`	無効なテキスト、音声、モデル、または出力形式です。ペイロードを修正する
`401`	認証に失敗しました	ポーリングを停止し、資格情報を更新します。
`402`	クレジットまたは割り当てが不十分です	キューを一時停止する
`404`	タスク ID はこの API キーにとって不明です	同じアカウントに対して返された ID を保存していることを確認してください
`429`	作成リクエストまたはポーリングリクエストが多すぎます	タスクを終了してタスク ID を維持します

非同期ジョブ v1

非同期ジョブ

ジョブの作成

仕事を得る

失われたタスク ID の復元

請求とクレジット

エラー

このページ