Batch запросы
Много запросов одним пакетом, результаты забираете позже. Удобно, когда ответ не нужен сразу: прогон датасета, ночная генерация, массовые эмбеддинги.
Окно выполнения — 24 часа у большинства провайдеров; модели Google могут выполняться до 4 суток (см. срок пакета). После завершения результаты приходят в том же GET, отдельный файл скачивать не нужно.
Какие модели
Обычное имя из каталога: gpt-6-astra, gemini-3.8-flash, claude-opus-4.8. Batch есть, если у модели в каталоге поле batch:
{
"batch": { "discount": 0.5, "window": "24h" }
}Прямые маршруты отдельных провайдеров в Batch не ходят — только модели с полем batch.
Эндпоинты
| Метод | Путь | Что делает |
|---|---|---|
POST | /v1/batches | Создать пакет, 202 Accepted |
GET | /v1/batches | Список ваших пакетов |
GET | /v1/batches/{id} | Статус и результаты |
DELETE | /v1/batches/{id} | Удалить входные данные и результаты завершённого пакета |
Отмены нет: провайдер начинает работу сразу и выставляет нам счёт независимо от того, ждёте вы результат. «Отмена» означала бы вернуть вам деньги за уже оплаченную нами работу. DELETE — это не отмена: он работает только для завершённого пакета.
Bearer, что для чатаФорма запроса
endpointmodelrequestscustom_id и bodyprovider{ "only": ["anthropic"] } закрепляет пакет за конкретным провайдером. Кроме only, в Batch ничего не принимается: sort, order и прочее вернут 400. Если ни у одного из перечисленных провайдеров нет Batch для этой модели — 404completion_window24hcustom_id уникален внутри пакета. body — то же, что вы бы отправили на выбранный endpoint. Модель в body можно не ставить: берётся верхний model. Если поставить — должно совпасть. stream: true в body не поддерживается.
Весь пакет выполняет один провайдер. По умолчанию выбирается самый дешёвый из тех, у кого есть Batch для модели.
Один пакет — одна модель и один endpoint, не больше 10 000 запросов.
endpoint | API |
|---|---|
/v1/chat/completions | Chat Completions |
/v1/responses | Responses |
/v1/messages | Messages |
/v1/embeddings | Embeddings |
Отправка
curl https://aitunnel.83.141.93.205.nip.io/__api/v1/batches \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-aitunnel-xxx" \
-d '{
"endpoint": "/v1/chat/completions",
"model": "claude-opus-4.8",
"requests": [
{
"custom_id": "req-0001",
"body": {
"messages": [
{ "role": "user", "content": "Суммируй AITUNNEL одним предложением." }
]
}
}
]
}'Успешный POST возвращает 202 и объект со статусом validating — пакет принят и встал в очередь, это ещё не готовые ответы.
{
"id": "batch_123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"model": "claude-opus-4.8",
"completion_window": "24h",
"status": "validating",
"created_at": 1782097200,
"finalized_at": null,
"expires_at": 1782183600,
"request_counts": {
"total": 1,
"completed": 0,
"failed": 0
},
"usage": null,
"results": null,
"error": null
}completion_window принимает только 24h. Сколько пакет может выполняться на самом деле, зависит от провайдера, которому он достался: expires_at в ответе — время (unix, секунды), после которого провайдер перестаёт над ним работать.
Опрос
curl https://aitunnel.83.141.93.205.nip.io/__api/v1/batches/batch_123 \
-H "Authorization: Bearer sk-aitunnel-xxx"Цепочка статусов:
validating → in_progress → finalizing → completedЕщё бывают failed, expired, cancelling, cancelled. Терминальные: completed, failed, expired, cancelled. Опрашивайте, пока не дойдёте до одного из них.
Опрос нужен только чтобы узнать результат. Пакет мы досчитываем сами: раз в минуту планировщик проверяет незавершённые задачи, поэтому резерв освобождается без вашего участия — даже если процесс, отправивший пакет, давно завершился. Можно спокойно закрыть скрипт и вернуться за results позже.
Сразу после POST пакет может пару десятков секунд не находиться у провайдера — в это время GET вернёт краткую запись о пакете со статусом pending. Это нормально, повторите опрос.
Краткая запись — тот же объект пакета, собранный из нашей записи о нём: id, object, endpoint, model, status, created_at и expires_at (unix, секунды), request_counts, request_count, usage, error и results: null. Её же отдаёт список пакетов. Читать её можно тем же кодом, что и полный ответ.
request_counts — прогресс: total, completed, failed.
Пока пакет не completed, results равен null. После — массив в том же ответе. Каждый элемент склеивается со входом по custom_id. Заполнено ровно одно: response или error. У запроса, который не выполнился, причина — в error.message.
{
"id": "batch_req_123",
"custom_id": "req-0001",
"response": {
"status_code": 200,
"request_id": "request_123",
"body": {
"id": "gen-…",
"object": "chat.completion",
"model": "claude-opus-4.8",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "AITUNNEL — единый API к сотням моделей с оплатой в рублях."
},
"finish_reason": "stop"
}
]
}
},
"error": null
}Ответ модели в response.body приходит как есть: текст, переносы строк и аргументы вызовов инструментов не меняются. Большой пакет — это большой ответ (сотни мегабайт): он отдаётся потоком, читайте его так же и не обрывайте соединение по короткому таймауту.
Если пакет завершился со статусом failed, причина — в error.message самого пакета:
{
"id": "batch_123",
"object": "batch",
"status": "failed",
"results": null,
"error": {
"message": "Batch request 'req-0002' contains unsupported 'input_audio' content."
},
"usage": { "cost": 0, "cost_rub": 0 }
}Удаление
Удалить входные данные и результаты раньше 30 дней:
curl -X DELETE https://aitunnel.83.141.93.205.nip.io/__api/v1/batches/batch_123 \
-H "Authorization: Bearer sk-aitunnel-xxx"{ "id": "batch_123", "object": "batch", "deleted": true }Работает только для пакета в терминальном статусе (completed, failed, expired, cancelled). Пока пакет выполняется, ответ — 409. Удаление не влияет на списание: итог уже посчитан, запись о пакете и расход в статистике остаются. Повторный DELETE тоже вернёт deleted: true. Если ответ — 5xx, повторите запрос.
Списание
При POST на балансе резервируется оценка (худший случай по составу пакета, уже со скидкой Batch). Резерв — это не списание: деньги удержаны, но ещё не потрачены, и в истории расходов их нет.
Когда пакет доходит до терминального статуса, списывается факт, а лишнее возвращается. При failed / expired / cancelled резерв обычно возвращается целиком. Но если провайдер успел выполнить часть запросов и выставил за них счёт, списывается эта часть — сумма в usage.cost_rub. Больше зарезервированного с вас не спишут: если провайдер выставил нам больше, разницу оплачиваем мы.
Итог в рублях — usage.cost_rub после completed.
У пакета, который закончился как failed, expired или cancelled и за который ничего не списано, результатов нет: GET отдаёт краткую запись со статусом, error.message и usage.cost_rub: 0.
Пакет completed с usage.cost_rub: 0 — это пакет, в котором не выполнился ни один запрос. Его results читаются как обычно: в каждом элементе error с причиной. Ответы без списания не выдаются: у элемента, по которому провайдер всё же хранит ответ, вместо него будет error.type: "not_billed".
Срок пакета
У пакета есть жёсткий срок: если к нему результата нет, пакет переводится в expired и резерв возвращается полностью. Зависнуть навсегда, удерживая деньги, пакет не может.
Срок — это срок провайдера, которому достался пакет, плюс два часа запаса:
| Провайдер | Работает над пакетом | Наш срок |
|---|---|---|
| Большинство (OpenAI, Anthropic и другие) | до 24 часов | 26 часов |
| Google AI Studio | до 48 часов | 50 часов |
| Google Vertex | до 96 часов | 98 часов |
Провайдер известен только после POST, поэтому срок берётся из его ответа и уточняется при опросе: если пакет до начала работы переехал к другому провайдеру, срок меняется вместе с ним. Наш срок — expires_at в краткой записи и в GET /v1/jobs; в полном ответе expires_at — срок самого провайдера. Большинство пакетов завершается за минуты.
Ошибки при отправке
| Код | Когда | Резерв |
|---|---|---|
400 | Пакет составлен неверно: нет endpoint или requests, повтор custom_id, модель без Batch, stream: true | Не брался |
402 | Не хватает на резерв. error.type — insufficient_balance или budget_exceeded, в error.metadata.required_rub — сумма резерва | Не брался |
4xx от провайдера | Провайдер отклонил пакет при приёме, тип provider_error | Возвращён сразу |
504 | Провайдер не принял пакет за 2 минуты, тип provider_unavailable | Возвращён сразу |
503 | Временный сбой на нашей стороне, тип service_unavailable | Не брался |
Форма ошибки общая для всего API — ошибки и отладка.
Список пакетов и кабинет
# Ваши пакеты, новые сверху
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/batches?limit=20" \
-H "Authorization: Bearer sk-aitunnel-xxx"
# Все асинхронные задачи (пакеты и видео), которые ещё держат резерв
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/jobs?active=true" \
-H "Authorization: Bearer sk-aitunnel-xxx"Параметры списка: status, active=true, limit (до 100), after. GET /v1/jobs дополнительно возвращает active_count и active_reserved_rub — сколько задач выполняется и сколько рублей они держат; у каждой записи есть kind, reserved_rub, а после расчёта cost и cost_rub (одно и то же число в рублях) и refunded_rub. Пакеты видны любому ключу своего аккаунта; id пакета из другого аккаунта и id видео-задачи в /v1/batches/{id} вернут 404. Ключ управления эти методы не вызывает: пакеты всего аккаунта и их результаты он читает через GET /aitunnel/jobs.
То же самое без кода — Логи → Задачи в кабинете: сумма резерва, статусы, фактическое списание и возврат, фильтры по типу и статусу. Результаты завершённого пакета оттуда можно выгрузить в JSON. Во вкладке «Запросы» рядом — только фактически потраченное, резервы туда не попадают.
Другие формы API
Все элементы одного пакета — один endpoint. Смешать формы — несколько пакетов.
Пример Messages:
{
"endpoint": "/v1/messages",
"model": "claude-opus-4.8",
"requests": [
{
"custom_id": "req-1",
"body": {
"max_tokens": 32,
"messages": [
{ "role": "user", "content": "Скажи привет." }
]
}
}
]
}/v1/embeddings работает так же, если у модели в каталоге есть batch. В body обязательно input: строка, массив строк или массив токенов. Картинки и прочий мультимодальный вход, а также input_type в Batch не принимаются — для них синхронный /embeddings.
Ограничения
- Картинки — только публичные
http(s)URL. Base64 иdata:URI не принимаются. URL работают, если модель принимает картинки и провайдер пакета умеет их скачивать: OpenAI, Anthropic, xAI, DeepInfra (только/v1/chat/completions). - Файлы (
input_fileв Responses,documentв Messages,fileв Chat Completions) — только по URL и только у OpenAI (только/v1/responses), Anthropic, Mistral и DeepInfra (только/v1/chat/completions). Байты файла и id загруженных файлов не принимаются. - Аудио и видео на входе не принимаются. В
/v1/chat/completionsотклоняются и запросы на нетекстовый вывод (modalities,audio,image_config). - Веб-поиск — только встроенный поиск провайдера:
web_searchу OpenAI в/v1/responses,web_search_20250305у Anthropic в/v1/messages. Плагинwebиweb_search_options(кроме моделей OpenAI) не принимаются. - Прочее: пустой
messages/input,stream: true,speed, лимит вывода меньше 1 и бета-функции Anthropic отклоняются. Неизвестные параметры отбрасываются, как в синхронном API. - На моделях Google все
bodyв пакете должны иметь одинаковыйresponse_format(или все без него), а дляjson_schema— одинаковую схему. Иначе пакет не пройдёт проверку: отправляйте отдельный пакет на каждыйresponse_format. - Имена пресетов в
modelне подходят — только каталожные id.
Большинство этих проверок проходит уже после 202: пакет переходит в failed, в error.message — причина, резерв возвращается полностью. Такие запросы отправляйте в синхронный API или закрепите пакет за подходящим провайдером через provider.only.