Новости

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

Материалы и готовый текст

Поиск учитывает период, зафиксированный в заказе. Полные извлечённые оригиналы сохраняются с идентичностями и происхождением; модели читают их страницы без нового платного извлечения. Известный отказ URL при агентском чтении возвращается отдельно для этого адреса; допустимые страницы пакета читаются дальше. Запрещённый адрес не отправляется провайдеру и не получает платного чтения. Сохранённые оригиналы используются до нового DNS-допуска, а каждый новый запрос и перенаправление сохраняют сетевую защиту. Этот исход не доказывает полноту остальных материалов и не разрешает повтор неизвестного внешнего эффекта. Сохранённая ошибка отдельного поиска или извлечения передаётся автору как данные. Он может продолжить по другим настоящим оригиналам или сделать другой разрешённый запрос. Исходный неизвестный запрос не отправляется повторно, в том числе в другом пакете чтения тех же адресов. Ошибка не заменяет прочитанный источник. Выпуск может быть готов к прослушиванию, пока расход прежнего запроса остаётся на сверке с сохранённым удержанием. Поисковые выдержки и уведомления помогают найти ссылки. Исследовательский агент оценивает актуальность и содержание оригиналов относительно сохранённого времени наблюдения asOf в UTC. Дата публикации, дата события и время обнаружения различаются. Неизвестная дата публикации остаётся неизвестной; запрошенный период не позволяет придумать недостающую дату. Прежний анонс не доказывает, что событие состоялось.

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

Длительность служит ориентиром. Более короткий содержательный выпуск допустим; расчётные слова, символы, минуты и число источников сами по себе не вызывают отказа или платной переписи. Модель может ошибаться, поэтому её решения не являются гарантией качества. Отсутствие событий, отсутствие подтверждения, прерванный сбор и ошибка обработки различаются; подтверждённые расходы остаются в чеке. Неизвестный внешний результат не объявляется успешным. task.errorCode сохраняет NEWS_RESEARCH_UNCONFIRMED, если найденные материалы не удалось подтвердить для выбранной темы и периода, и NEWS_RESEARCH_INCOMPLETE, если исследование не завершено. Уведомление Telegram объясняет ту же причину на русском или английском без текста ошибки провайдера. Завершённый поиск без подходящих событий отменяет выпуск без выдуманного аудио.

Эндпоинты

Метод и путь	Разрешение	Результат
GET /api/v1/news/voices	news:quote	доступные голоса
POST /api/v1/news/quotes	news:quote	201 {quote} с quoteId, credits, maximumCredits, expectedCredits, forecast, expiresAt
POST /api/v1/news	news:create	202 {operation: {taskId, status: "started"}}
GET /api/v1/news/:taskId	news:read	{task: {taskId, status, stageCode, progressPercent, balancePause?, recovery?, accounting?, errorCode?}}
GET /api/v1/news/:taskId/result	news:read	текст, тема, период, голос, длительность, источники и глоссарий
GET /api/v1/news/:taskId/receipt	news:read	{receipt}
POST /api/v1/news/:taskId/cancel	news:create	{success: true}
GET /api/v1/news/:taskId/audio	news:read	аудио, поддерживает Range

stageCode — queued, researching, drafting, synthesizing, paused_insufficient_credits, ready, failed или cancelled. Пока выпуск не готов, result и audio отвечают 409 NEWS_NOT_READY; отменить законченный выпуск нельзя (409 NEWS_NOT_CANCELLABLE).

expectedCredits — примерная стоимость; forecast показывает подтверждённые границы оценки и уровень уверенности. Недоступные границы остаются null, а не выдуманным диапазоном. В ответе maximumCredits: null означает работу по балансу без лимита выпуска. Developer News не принимает это поле в запросе; расход ключа можно ограничить его отдельной квотой. Создание не удерживает весь предел: оплаченные действия списываются по мере выполнения. При нехватке баланса до следующего действия задача переходит в paused_insufficient_credits и продолжает работу с тем же taskId после пополнения. Чек показывает уже списанные кредиты, которые остаются списанными при отмене или ошибке. Явный числовой лимит и квота ключа намеренно останавливают работу; пополнение их не меняет. При отмене уже атомарно допущенный модельный вызов завершает измерение и расчёт, но новые действия не запускаются. Неизвестный исход сохраняет удержание до настоящей сверки. Обычное продолжение оператором не повышает лимит News, отдельного API его изменения нет. Для default-null News такое изменение не требуется: после пополнения продолжается то же задание. В статусе balancePause содержит requiredCredits и availableCredits; errorCode различает OPERATION_SPENDING_LIMIT и API_KEY_QUOTA_EXCEEDED при отказе. Произвольный текст провайдера не передаётся.

Ожидание доступности средств сервиса модели отличается от нехватки кредитов пользователя. При валидной сохранённой отметке такого ожидания статус содержит recovery: {state: "waiting", reasonCode}: PROVIDER_FUNDING_READ_UNAVAILABLE означает временную недоступность данных о средствах сервиса, а PROVIDER_FUNDING_INSUFFICIENT — ожидание восстановления доступности сервиса. Такое ожидание не переводит задачу в failed и не требует повторять создание или пополнять баланс пользователя. Та же задача продолжается автоматически, когда условия восстановлены. accounting.capturedCredits и accounting.heldCredits, если доступны, показывают фактически списанные кредиты и текущее незавершённое удержание из исходного чека, включая резерв неизвестного эффекта до подтверждённой сверки. Отсутствие этих полей не означает нулевой расход. Неизвестный исход уже отправленного запроса сохраняет свою финансовую защиту и не становится ожиданием средств сервиса.

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

Поля запроса

Поле	Значение
topic	идентификатор темы из публичного каталога GET /api/config/topics или ваша тема (ct_…); свободный текст и чужие темы — 400 INVALID_NEWS_TOPIC
period	today, week или month
voiceId, language	голос из /voices; ru или en
preferences	необязательно: length_preset — express, standard (по умолчанию), detailed; detail_level — telegram, standard (по умолчанию), detailed; this_day_in_history — boolean, по умолчанию false

Любое другое поле — 400 UNSUPPORTED_API_FIELD. Задача видна только ключу, который её создал; для остальных — 404 TASK_NOT_FOUND.

this_day_in_history: true допускает подтверждённый исторический контекст в том же денежном бюджете. Исторические материалы не выдаются за текущую новость. При отсутствии подходящего подтверждения необязательная рубрика пропускается.

Пример

news:quote, news:create

1 · quote

curl -s -X POST https://cast.witqq.dev/api/v1/news/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "topic": "technology",
  "period": "week",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

2 · create

curl -s -X POST https://cast.witqq.dev/api/v1/news \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "topic": "technology",
  "period": "week",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'