Синхронный синтез речи 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"Используйте доступную модель и голос, в modelIds которого она указана. Ограничения, форматы и параметры берите из capabilities.
Синхронная генерация
POST /api/open/v3/speech/ttscurl "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.