동기 텍스트 음성 변환 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	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

이 페이지