Цены и списание

Котировка

POST …/quotes считает цену операции и возвращает quote:

• quoteId — передаётся в запрос создания вместе с неизменённым телом котировки;
• credits — приблизительный прогноз (expectedCredits, либо 0 при неизвестной оценке), не разрешение на списание;
• maximumCredits — отдельный лимит операции либо null без лимита на выпуск;
• expectedCredits — приблизительная стоимость Podcast или News;
• expiresAt — срок действия котировки.

Котировка Podcast дополнительно показывает режим и предполагаемые этапы. Котировки Podcast и News используют биллинг версии 4 и показывают диапазон и уверенность прогноза. Низкая уверенность означает, что достаточных сопоставимых данных пока нет. Поле maximumCredits в запросе Podcast необязателен: отсутствие поля или null означает работу по доступному балансу без лимита на выпуск. Явное положительное целое число в безопасном диапазоне JSON не уменьшается по длительности, качеству или прогнозу. Ориентир может быть выше выбранного предела; он не служит разрешением на расход. Developer News не принимает maximumCredits во вводе и возвращает null; отдельная квота API-ключа продолжает ограничивать его расход.

Создание и списание

Котировка сохраняет согласованные тарифы опубликованной пары ценовой политики и каталога исполнения. Последующее изменение цен не переписывает уже принятую операцию.

Создание принимает то же тело, что и котировка, плюс quoteId. Для нового Podcast и News сервис не резервирует весь предел. Перед каждым платным запросом он удерживает максимум только этого запроса с баланса владельца и из квоты ключа. После подтверждённого результата списывает прирост накопленной стоимости, округлённой в кредиты, и освобождает неиспользованную часть удержания. Если средств не хватает до следующего запроса, тот же taskId ждёт пополнения и затем продолжает работу автоматически. Отмена и ошибка сохраняют уже подтверждённые расходы в чеке; неопределённый результат провайдера удерживается до сверки: истечение срока само по себе не доказывает отсутствие расхода и не разрешает повтор вызова. Доказанный неотправленный модельный запрос освобождает своё удержание без списания; наблюдаемый нулевой расход настоящего вызова сохраняет согласованное правило минимальной цены. При достижении предела выпуска или квоты ключа при достаточном балансе операция сообщает соответствующую причину вместо ожидания пополнения. Владелец допустимого failed Podcast может отдельно подтвердить повышение или снятие лимита через Continue в мини-приложении: сохраняются та же задача, операция, тарифы и уже оплаченные результаты. Создающий API-ключ может подтвердить допустимое продолжение Podcast или озвучки через отдельную котировку; он не получает право подтверждать отсутствие внешней отправки. Обычное продолжение News не повышает заданный числом лимит.

Исторические чеки Podcast и News сохраняют исходные суммы резерва и расчёта; задачи с неподдерживаемым сохранённым планом не возобновляются. Чек (…/receipt) показывает версию биллинга, удержанное, списанное и освобождённое; при ожидаемой сверке итог ещё не окончательный. У V4 maximumCredits показывает действующий лимит, originalMaximumCredits — исходный; budgetAuthorization, если есть, связывает изменение с успешным подтверждением Continue. null означает отсутствие лимита, а не нулевой расход.

Текущее heldCredits включает ещё не разрешённые удержания, в том числе по неизвестному результату провайдера. Накопленное reservedCredits не равно текущему удержанию. Независимые подтверждённые данные провайдера могут уточнить расход исходного вызова, но не восстановить потерянный текст или аудио. Отсутствие идентификатора вызова или ответ 404 не доказывает нулевой расход. Такая сверка применяется и к завершённому модельному вызову, если его денежный расход ещё неизвестен. Она уточняет только исходные денежные сведения в пределах принятого соглашения; готовое содержание не открывается заново и модельный вызов не покупается повторно.

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

Тело, отличающееся от котировки, получает 409 QUOTE_FINGERPRINT_MISMATCH; котировка другого ключа — 409 API_KEY_QUOTE_MISMATCH; истёкшая или уже использованная — 409 QUOTE_EXPIRED или 409 QUOTE_ALREADY_CONSUMED.

Идемпотентность

Заголовок Idempotency-Key обязателен для создания (8–128 символов A-Za-z0-9._:-). Повтор с тем же ключом и телом возвращает ту же операцию; с другим телом — 409 IDEMPOTENCY_CONFLICT. Идемпотентность действует в пределах одного API-ключа: одинаковый клиентский ключ у двух разных API-ключей создаёт две операции.

Сохраните тело вместе с quoteId и ключом до отправки. Повтор принятого создания требует той же котировки, ввода и создающего API-ключа; новая котировка с прежним Idempotency-Key не является повтором исходной команды. При неопределённом ответе продолжайте проверять или повторять исходную команду. Только явное acceptance: "rejected" подтверждает отказ до принятия.

Что не возвращается

Ответы содержат кредиты, единицы провайдера, идентификаторы и статусы — и никогда не содержат внутреннюю стоимость в долларах, наценку, выплаты или маржу.