同期テキスト読み上げ v3

HTTP v3 で音声を同期生成するか、復旧可能な非同期ジョブを作成します。

HTTP TTS v3 は推奨されるプロバイダー非依存契約です。プロバイダーのルーティングはプラットフォームが担当し、クライアントは公開 voiceId と modelId を使用します。

Base URL

https://kittaai.com/api/open/v3

同期と非同期の選択

短いテキストは同期、長文・バッチ・結果の再取得が必要な処理は Jobs を使用します。

モデルと音色の確認

curl "https://kittaai.com/api/open/v3/speech/tts/capabilities"
curl "https://kittaai.com/api/open/v3/voices?page=1&pageSize=20&includePersonal=false" \
  -H "Authorization: Bearer $KITTA_API_KEY"

available なモデルと、その modelIds に対象モデルを含む音色だけを使用します。上限、形式、制御項目は capabilities を確認してください。

同期生成

POST /api/open/v3/speech/tts

curl "https://kittaai.com/api/open/v3/speech/tts" \
  -H "Authorization: Bearer $KITTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: tts-example-001" \
  -d '{"text":"Hello","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}' --output speech.mp3

リクエストフィールド

field	type	required	constraints
`text`	string	yes	1–10,000
`voiceId`	string	yes	must support `modelId`
`modelId`	string	no	public model ID; omitted uses voice provider default
`format`	string	no	`mp3`, `wav`, `ogg`; default `mp3`
`speed`	number	no	0.5–2; default 1
`volume`	number	no	-20–20; default 0
`pitch`	number	no	-12–12
`stability`	number	no	0.5–1.5
`similarity`	number	no	0.5–1.5
`language`	string	no	1–64 characters in v3
`emotion`	string	no	1–64 characters in v3
`instruction`	string	no	up to 1,600 characters
`textNormalization`	boolean	no	structured-text normalization

Unknown fields are rejected. Unsupported generic controls are listed in X-OpenAPI-Ignored-Parameters.

成功レスポンス

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Request-Id: tts-example-001
X-OpenAPI-Quota-Remaining: 99994
X-OpenAPI-Credits-Used: 6

<binary audio data>

成功時は音声バイナリです。HTTP ステータスと Content-Type を確認し、エラーは JSON として処理します。

非同期ジョブ

POST /speech/tts/jobs
GET /speech/tts/jobs/{jobId}
GET /speech/tts/jobs/{jobId}/audio?download=1
Authorization: Bearer KITTA_API_KEY

task.taskId を保存します。pending と processing は非終端、success、partial_fail、fail は終端です。

エラーと再試行

Errors use {"code":"ERR_REQUEST_ID_CONFLICT","message":"...","requestId":"..."}. 400 不正な要求、401 無効なキー、402 クォータ不足、404 未検出、409 冪等性競合、413 過大、429 制限、500 生成失敗。

冪等性と課金

同一リクエストの再試行時だけ安定した X-Request-Id を再利用します。完了済み同期音声は再送されませんが、Jobs は再取得できます。

機械可読契約と移行

GET /api/open/v3/openapi.json

既存 v1/v2 クライアントは互換です。新規統合は v3 を使用します。 Migration guide.

同期テキスト読み上げ v3

このページ