Подкасты

/api/v1/podcasts создаёт те же подкасты, что и мини-приложение, в любом из трёх режимов сценария. Готовый подкаст появляется в библиотеке владельца как приватный и публикуется только из мини-приложения.

Эндпоинты

Метод и путь	Разрешение	Результат
`GET /api/v1/podcasts/voices`	`podcasts:quote`	доступные голоса
`POST /api/v1/podcasts/quotes`	`podcasts:quote`	`201 {quote}`
`POST /api/v1/podcasts`	`podcasts:create`	`202 {operation: {podcastId, taskId, status, created, creditsCharged}}`
`GET /api/v1/podcasts/:podcastId`	`podcasts:read`	`{podcast}` со `status`, `stageCode`, прогрессом плана и доступными `recovery`/`accounting`
`GET /api/v1/podcasts/:podcastId/receipt`	`podcasts:read`	`{receipt}`
`POST /api/v1/podcasts/:podcastId/cancel`	`podcasts:create`	`{success: true}`
`POST /api/v1/podcasts/:podcastId/continuation-quote`	`podcasts:quote`	`201 {quote}` для допустимой failed-задачи
`POST /api/v1/podcasts/:podcastId/continue`	`podcasts:create`	`202 {operation}` той же задачи
`GET /api/v1/podcasts/:podcastId/audio`	`podcasts:read`	аудио, поддерживает `Range`

Режимы

prepared_text (по умолчанию) — ваш текст озвучивается как есть.
raw_text — агент превращает черновые заметки в текст для озвучки.
topic — агент пишет сценарий по теме; с grounding: "quick" или "deep" он сначала ищет и читает источники. Для темы по результатам исследования статус подкаста показывает сводку исследования.

grounding: "none" использует общие знания модели без поиска, проверки свежести или подтверждения по источникам. Все режимы используют актуальный план; неподдерживаемая конфигурация отклоняется до платной работы. Готовый текст озвучивается полностью после нормализации пробелов; подготовка черновых заметок сохраняет существенное содержание и окончание исходника.

Quick/Deep ищут материалы по теме без обязательного новостного периода и автоматически читают найденные страницы в пределах денежного бюджета и реальных ограничений провайдера. Полные оригиналы сохраняются; агенты читают нужные страницы без повторного извлечения. Сценарий использует подтверждённые материалы или выбранные версии библиотеки; поисковых выдержек недостаточно. Если пригодных доказательств нет, выпуск прекращается до написания и озвучки; повтор с теми же материалами не устранит причину. Уточните тему или передайте доступные страницы в urls, затем запросите новую котировку. Можно передать sourceVersionIds уже сохранённых собственных источников; создание и обновление библиотеки выполняются в мини-приложении. При агентском чтении известный отказ отдельного URL не мешает прочитать допустимые страницы пакета. Агент получает безопасную причину и может выбрать другой источник; запрещённый адрес не отправляется провайдеру и не оплачивается как чтение. Сохранённый оригинал используется до новой проверки DNS, а каждый новый запрос и перенаправление сохраняют сетевую защиту. Неизвестный платный исход, отмена и денежный или операторский отказ не становятся обычной ошибкой источника. Пригодность оставшихся материалов по-прежнему оценивается содержательно. Сохранённая ошибка отдельного поиска или извлечения передаётся автору как данные. Он может продолжить по другим настоящим оригиналам или сделать другой разрешённый запрос. Исходный неизвестный запрос не отправляется повторно, в том числе в другом пакете чтения тех же адресов. Ошибка не заменяет прочитанный источник. Выпуск может быть готов к прослушиванию, пока расход прежнего запроса остаётся на сверке с сохранённым удержанием. Отключённый оператором неиспользуемый поиск или извлечение не блокирует котировку и выбор сценария с пригодными оригиналами вашей библиотеки. Агенты читают сохранённые оригиналы без нового внешнего запроса. Если для восполнения пробела в материалах потребуется новый поиск или извлечение, доступность провайдера проверяется до платного вызова и отправки запроса. Написание сценария и озвучка остаются новой работой и оплачиваются по факту. Без маршрута извлечения или пригодного текста библиотеки котировка возвращает 503 RESEARCH_EXTRACTION_UNAVAILABLE до платной работы. Если используете только веб-источники, дождитесь восстановления маршрута извлечения оператором и запросите новую котировку. Подтверждённые вызовы принятого задания оплачиваются по факту, даже если исследование не дало пригодного материала.

Поля запроса

Поле	Режимы	Значение
`mode`	все	`prepared_text`, `raw_text` или `topic`
`title`	все	непустое название
`text`	`prepared_text`, `raw_text`	исходный текст
`topic`	`topic`	тема
`voiceId`, `language`	все	голос из `/voices`; `ru` или `en`
`durationMinutes`	все	целое 3–60; ориентир глубины темы и прогноз длительности. В текстовых режимах без поля оценка выводится из исходника и скорости голоса. Минуты не ограничивают исходник, число блоков или длину результата; фактическая длительность определяется по аудио
`lengthPreset`	`topic`	`express`, `standard` или `detailed`; для `topic` нужен `lengthPreset` или `durationMinutes`
`grounding`	`topic`	`none` (по умолчанию), `quick` или `deep`
`focus`, `urls`	`topic` с исследованием	фокус исследования и публичные HTTP(S)-адреса для чтения
`sourceVersionIds`	`topic` с исследованием	версии ваших сохранённых источников (`rsv_…`)
`templateId`, `templateRevision`	все	встроенный шаблон или ваш `tpl_…`
`quality`	все	`economy`, `balanced` (по умолчанию) или `quality`
`maximumCredits`	все	необязательный положительный safe integer лимит в кредитах; отсутствие или `null` — работа по балансу без лимита выпуска; прогноз его не уменьшает

Любое другое поле — 400 UNSUPPORTED_API_FIELD до начала работы. Выбор моделей, повторное использование исследования или сценария и идентификатор пользователя в публичный контракт не входят; источники и шаблоны других пользователей отклоняются. В мини-приложении готовый исследовательский корпус и готовый сценарий выбираются отдельно от приватности источников. Законный публичный корпус доступен без нового поиска, но новый сценарий требует доступных модельных маршрутов. Переозвучивание готового сценария не зависит от поиска и моделей. Котировка проверяет право владельца использовать сохранённые материалы или сценарий; каталог предоставляет варианты настройки, а доступность и примерная стоимость выбранного запроса определяются его котировкой. Настройка провайдера не подтверждает успешный рабочий вызов.

После исследования автор готовит единый сценарий для озвучки. Черновые заметки проходят один этап подготовки текста, а готовый сценарий поступает прямо в озвучку. Автор отвечает за основания, полноту, язык и связность; обязательной отдельной проверки каждого блока и смысловых сертификатов нет. Программа проверяет формат ответа, принадлежность материалов и сохранность результатов. Общая инструкция исследования просит сохранять предмет числа, единицу и период, отличать план или мощность от результата, намерение от совершённого действия. Автор сверяет итоговую записку и формулировки с оригиналами в том же вызове; отдельная оплачиваемая проверка не добавляется.

Сценарий не растягивается до расчётного объёма. Слова, символы, токены, минуты и число источников служат ориентирами и сами по себе не вызывают отказа или платной переписи. Более короткий содержательный выпуск допустим; подготовка черновых заметок сохраняет существенные сведения и окончание исходника. Качество содержания зависит от решений модели и не гарантируется кодом. Завершённый текст сохраняется для продолжения. Достоверно полученный ответ, оборванный ограничением выхода модели, дописывается с сохранённого префикса без перепокупки начала. Неизвестный исход уже отправленного запроса требует сверки и не разрешает автоматический повтор. Новые модельные маршруты требуют подтверждённого контекста от 200 000 токенов и поддержки инструментов; принятые задания сохраняют свои маршруты и тарифы.

Новая котировка Podcast показывает примерную стоимость (expectedCredits) и отдельно предел (maximumCredits, либо null без лимита выпуска). Создание не резервирует весь предел: каждый платный запрос оплачивается по факту. При нехватке денег перед следующим запросом status и stageCode переходят в paused_insufficient_credits, а balancePause содержит требуемую и доступную суммы. После пополнения система продолжает тот же taskId без нового запроса создания. Ошибка OPERATION_SPENDING_LIMIT не снимается пополнением. Владелец допустимого failed Podcast может подтвердить повышение или снятие лимита через Continue в мини-приложении на той же задаче и финансовой операции, без перепокупки завершённых действий. Создающий API-ключ может выполнить это через continuation-quote и continue; поля и порядок запросов описаны в Статусе и продолжении. API_KEY_QUOTA_EXCEEDED остаётся отдельным ограничением ключа. При ожидании доступности средств сервиса модели сохранённая валидная отметка возвращается как recovery: {state: "waiting", reasonCode}. PROVIDER_FUNDING_READ_UNAVAILABLE означает временно недоступные данные о средствах сервиса; PROVIDER_FUNDING_INSUFFICIENT — ожидание восстановления доступности сервиса. Эта пауза не требует пополнения баланса пользователя, нового create или Continue: система автоматически продолжает тот же taskId и финансовую операцию после восстановления условий. Статус не становится ошибкой только из-за такого ожидания. Голосовой этап также может ждать с кодом VOICE_PROVIDER_WAITING или VOICE_LOCAL_COMPLETION_WAITING: система продолжает ту же задачу автоматически и использует сохранённое аудио без повторной покупки. Эти паузы не требуют пополнения или Continue; их причины и границы повтора описаны в Статусе и продолжении. Владельческий ответ также может содержать accounting.capturedCredits и accounting.heldCredits — фактическое накопительное списание и текущее незавершённое удержание из исходного чека. Удержание включает резерв неизвестного эффекта до подтверждённой сверки. Поля передаются только при наличии достоверных сумм в чеке; отсутствие полей не означает нулевой расход. Эти сведения читаются только после проверки владельца и точного создающего API-ключа. Неизвестный уже отправленный эффект остаётся защищённым; отсутствие ID или денежного наблюдения само по себе не разрешает новый модельный запрос. Отмена закрывает допуск новых действий. Уже атомарно допущенный модельный вызов завершается и сохраняет фактические расходы, не запуская следующую работу или аудио. Неизвестный исход сохраняет удержание до настоящей сверки; отменённая задача не получает Continue.

Примеры

Тема с быстрым поиском

podcasts:quote, podcasts:create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "topic",
  "title": "Quantum sensors",
  "topic": "How quantum sensors work and where they are used today",
  "lengthPreset": "express",
  "grounding": "quick",
  "voiceId": "yandex-speechkit:jane",
  "language": "en"
}'

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "topic",
  "title": "Quantum sensors",
  "topic": "How quantum sensors work and where they are used today",
  "lengthPreset": "express",
  "grounding": "quick",
  "voiceId": "yandex-speechkit:jane",
  "language": "en"
}'

Готовый текст

podcasts:quote, podcasts:create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "prepared_text",
  "title": "Утренний выпуск",
  "text": "Доброе утро. Сегодня три коротких истории о науке и технологиях. Первая — о новых квантовых сенсорах, которые измеряют магнитное поле мозга без громоздких установок. Вторая — о спутниках, которые следят за таянием ледников. Третья — о том, как города учатся экономить воду.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "prepared_text",
  "title": "Утренний выпуск",
  "text": "Доброе утро. Сегодня три коротких истории о науке и технологиях. Первая — о новых квантовых сенсорах, которые измеряют магнитное поле мозга без громоздких установок. Вторая — о спутниках, которые следят за таянием ледников. Третья — о том, как города учатся экономить воду.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

Черновые заметки

podcasts:quote, podcasts:create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "raw_text",
  "title": "Итоги недели команды",
  "text": "Заметки: релиз мобильного приложения перенесли на вторник; в поддержку пришло на 20% меньше обращений; новая страница цен подняла конверсию; в пятницу общая встреча в 16:00.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru",
  "durationMinutes": 5
}'

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "raw_text",
  "title": "Итоги недели команды",
  "text": "Заметки: релиз мобильного приложения перенесли на вторник; в поддержку пришло на 20% меньше обращений; новая страница цен подняла конверсию; в пятницу общая встреча в 16:00.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru",
  "durationMinutes": 5
}'