Texto para fala síncrono v3

Gere áudio de forma síncrona ou crie tarefas assíncronas recuperáveis com HTTP v3.

HTTP TTS v3 é o contrato neutro recomendado. A plataforma gerencia o provedor; o cliente usa voiceId e modelId públicos.

Base URL

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

Escolher entrega síncrona ou assíncrona

Use síncrono para texto curto. Use Jobs para texto longo, lotes ou resultados recuperáveis.

Descobrir modelos e vozes

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"

Use apenas modelos disponíveis e uma voz cujo modelIds contenha o modelo escolhido. Leia limites, formatos e controles em capabilities.

Gerar de forma síncrona

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

Campos da solicitação

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.

Resposta bem-sucedida

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>

O sucesso retorna áudio binário. Verifique o status HTTP e Content-Type; erros são JSON.

Tarefas assíncronas

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

Salve task.taskId. pending e processing não são finais; success, partial_fail e fail são finais.

Errors use {"code":"ERR_REQUEST_ID_CONFLICT","message":"...","requestId":"..."}. 400 solicitação inválida; 401 chave inválida; 402 cota insuficiente; 404 ausente; 409 conflito de idempotência; 413 grande; 429 limite; 500 falha.

Idempotência e cobrança

Reutilize uma X-Request-Id estável apenas para a mesma solicitação. Áudio síncrono concluído não é repetido; Jobs continuam consultáveis.

Contrato legível por máquina e migração

GET /api/open/v3/openapi.json

Clientes v1/v2 continuam compatíveis. Novas integrações usam v3. Migration guide.