Асинхронные задания

Используйте асинхронные задания TTS для длинного текста, пакетной генерации, рабочих процессов в стиле веб-перехватчика и потоков пользовательского интерфейса, где пользователи могут покинуть страницу, пока аудио еще обрабатывается.

Создать задание

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

Запрос

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1,
  "pitch": 0,
  "language": "auto",
  "emotion": "neutral",
  "instruction": "Speak naturally",
  "textNormalization": true
}

Сохраните хэш текста, запрошенный голос и возвращенный идентификатор задачи в своей базе данных. Если ваш рабочий процесс выходит из строя после создания, опрос по идентификатору задачи безопаснее, чем создание второго задания.

В примере используется голосовой тест общедоступной системы 00a1b221-6137-4b73-ad62-b0cbce134167. Замените его предпочитаемым голосовым идентификатором после проверки соединения.

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'

Ответ

Конечная точка возвращает 202 Accepted. Сохраните task.id перед началом опроса.

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

Получить работу

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

Значения статуса: pending, processing, success, partial_fail и fail.

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

Для task.segments[].playbackUrl требуется тот же заголовок. Не создавайте новое задание для восстановления загрузки.

Восстановление потерянного ID задачи

Если запрос на создание достиг сервера, но клиент не получил ответ 202 Accepted, сначала запросите список недавних заданий:

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

Результаты отсортированы от новых к старым. Сопоставьте локальный запрос по createdAt, textFingerprint, voiceId и engineModelId. Поддерживаются параметры page, limit (не более 100), status и createdAfter в формате ISO 8601. Список содержит только фрагмент текста и не возвращает полный текст. После восстановления taskId продолжайте опрашивать существующее задание. Получение списка не расходует квоту API.

Выставление счетов и кредиты

Сервер резервирует creditsUsed один раз при принятии задания. Опрос, загрузка и повторная загрузка того же аудио не приводят к новому списанию. Неудачное предоплаченное задание возвращает кредиты через идемпотентный механизм.

Для пакета регулируйте параллелизм на своей стороне и проверьте Профиль перед добавлением большого количества задач. Если одна задача не удалась из-за недостаточного количества кредитов, приостановите выполнение rest пакета, пока владелец учетной записи не разрешит баланс.

Ошибки