文字轉語音（同步）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	yes in v3	public model ID
`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

本頁內容