Статус, чек, отмена и аудио
После создания у операции есть идентификатор: podcastId у подкастов и озвучки, taskId у новостей.
Все эндпоинты операции отвечают только ключу, который её создал; другой ключ того же владельца
получает 404.
GET …/:id возвращает текущий статус, stageCode и прогресс. Набор stageCode зависит от ресурса:
| Ресурс | stageCode |
Готово |
|---|---|---|
| Подкасты и озвучка | queued, researching, drafting, preparing, synthesizing, paused_insufficient_credits, completed, failed, cancelled |
completed |
| Новости | queued, researching, drafting, synthesizing, paused_insufficient_credits, ready, failed, cancelled |
ready |
paused_insufficient_credits ждёт пополнения и не является окончательным состоянием; тот же выпуск
продолжится автоматически. failed завершает текущий проход и не запускает автоматический повтор.
Допустимую сохранённую работу можно продолжить на той же задаче и финансовой операции без второй
покупки завершённых действий. Для failed Podcast и озвучки создающий API-ключ использует
POST …/:podcastId/continuation-quote, затем POST …/:podcastId/continue с полученным quoteId
и заголовком Idempotency-Key. Котировка принимает {} для сохранения лимита либо
{"maximumCredits": 100} для его повышения; {"maximumCredits": null} снимает лимит.
Понижение лимита запрещено.
Повтор Continue сохраняет исходную котировку и ключ запроса. Другой API-ключ того же владельца
получает 404; недопустимое продолжение — 409 PODCAST_CONTINUATION_UNAVAILABLE.
Для News продолжение доступно через мини-приложение или уполномоченного оператора и не изменяет
числовой лимит. Неизвестный внешний результат требует отдельного доказательства: API-ключ
не даёт права подтверждать отсутствие отправки. Если генерация подкаста завершилась ошибкой после подтверждения запроса провайдером и обрыва потока,
уполномоченный оператор может отдельно разрешить новый оплачиваемый вызов по сохранённым фактам;
исходный неизвестный расход при этом сохраняется. cancelled остаётся окончательным состоянием.
Подтверждённый внутренний HTTP 500 SpeechKit система учитывает как неоплаченный отказ и
сохраняет ожидание и автоматически повторяет только тот же аудиофрагмент после паузы. Ошибка посредника или
неизвестный исход не дают такого разрешения. Для старого неизвестного голосового запроса
уполномоченный оператор может отдельно разрешить новую платную попытку того же фрагмента;
исходное удержание остаётся до сверки. Если новая попытка тоже осталась с неизвестным исходом,
для следующей физической попытки нужно ещё одно решение по её точному запросу. Прежние
неизвестные расходы и удержания сохраняются; повтор решения не отправляет запрос снова.
API-ключ сам такого решения не принимает.
Опрашивайте статус с разумным интервалом:
у ключа есть лимит запросов в минуту (см. Лимиты).
Ошибка запроса статуса означает недоступное наблюдение, а не отказ самой генерации. Сохраните последний подтверждённый статус и повторите чтение. Не создавайте новый выпуск вместо проверки исходной операции; восстановление использует сохранённый вход и уже выполненные действия.
В статусе Podcast, озвучки и News необязательное recovery показывает безопасную причину сохранённого
ожидания с state: "waiting" и reasonCode:
PROVIDER_FUNDING_READ_UNAVAILABLEилиPROVIDER_FUNDING_INSUFFICIENT— ожидание доступности средств сервиса модели;VOICE_PROVIDER_WAITING— временная недоступность голосового сервиса после подтверждённого безопасного отказа;VOICE_LOCAL_COMPLETION_WAITING— завершение обработки сохранённого аудио или локального учёта результата.
Это не новый статус и не просьба пополнить кошелёк. Та же задача и финансовая операция продолжаются
автоматически после сохранённого времени повторной попытки и проверки допустимости работы.
Уже сохранённое аудио используется повторно; локальная ошибка сборки или учёта не покупает озвучку заново.
Не отправляйте новое создание или Continue для такого ожидания. Неизвестный внешний исход
не разрешает автоматический повтор оплачиваемого вызова.
Необязательное accounting содержит наблюдаемые capturedCredits и heldCredits из чека;
отсутствующие данные не означают ноль. Удержание может включать неизвестный исход прежнего вызова.
GET …/:id/receipt показывает версию биллинга, накопленный резерв, фактически списанное и
освобождённое. Текущее удержание heldCredits — остаток резерва после списания и освобождения;
он может сохраняться для неизвестного внешнего исхода до получения доказательств.
У Podcast и News версии 4 списание обновляется после каждого подтверждённого платного
действия; при ошибке или отмене уже выполненная работа остаётся списанной. Если исход провайдера
неизвестен, чек может ожидать сверки и после завершения генерации. Исторические чеки Podcast и News
сохраняют исходный резерв и расчёт; задачи с неподдерживаемым сохранённым планом не возобновляются.
Если поддержка вернула списание, refundedCredits
показывает возвращённые кредиты: они снова на балансе и в квоте ключа, а в итоге остаётся списание минус
возврат. У V4 maximumCredits — действующий лимит либо null без лимита выпуска,
originalMaximumCredits — исходный; необязательный budgetAuthorization связывает изменение с
успешным подтверждением Continue. Старые суммы и оплаченные результаты не переписываются.
POST …/:id/cancel останавливает незавершённую операцию, включая ожидающие пополнения Podcast и News;
доказанно неиспользованное удержание освобождается, подтверждённые расходы остаются в чеке.
Удержание по неизвестному результату провайдера сохраняется до подтверждающих данных.
Законченную операцию отменить нельзя.
GET …/:id/audio отдаёт готовое аудио с Accept-Ranges: bytes и приватным кэшированием без
сохранения. Один корректный диапазон возвращает 206 с Content-Range; некорректный, множественный
или невыполнимый — 416 RANGE_NOT_SATISFIABLE.
Ответ передаёт проверенный сохранённый аудиофайл потоком после проверки создающего API-ключа,
без загрузки всего файла в память. Используйте Content-Type ответа для определения формата:
аудио может быть MP3, WAV или Ogg, поэтому не назначайте расширение .mp3 всем ответам.
Браузерный плеер мини-приложения использует отдельную HttpOnly media-сессию и тот же файловый
поток; API-клиент продолжает передавать свой ключ в заголовке Authorization.