OpenAI Batch API: что это, когда выгоден и чем заменить через шлюз

OpenAI Batch API — это способ отправить сразу много запросов файлом, не ждать ответа и получить результаты позже по сниженной цене. У Anthropic есть похожий механизм. Ниже разберём, как это устроено, когда это выгодно и как получить сопоставимый результат, если вы работаете через шлюз, у которого пакетных эндпоинтов нет. Описание основано на документации OpenAI и Anthropic на момент проверки: условия там меняются, поэтому сверяйте цифры с актуальными страницами поставщиков.

Что такое Batch API

Обычный запрос синхронный: вы отправили, подождали, получили ответ. Пакетный режим работает иначе: вы собираете запросы в один файл, загружаете его, запускаете задачу и позже забираете файл с результатами. Платой за отсутствие мгновенного ответа служит скидка и более высокие лимиты.

Как это устроено у OpenAI

По руководству OpenAI по Batch API:

1. Готовится файл .jsonl, где каждая строка — отдельный запрос с обязательным уникальным custom_id, методом, адресом эндпоинта и телом запроса. Тело совпадает с телом обычного запроса к этому эндпоинту.
2. В одном файле допускается только одна модель.
3. Файл загружается через Files API с назначением batch.
4. Создаётся задача, окно выполнения сейчас может быть только 24h.
5. Статус проходит через validating, in_progress, finalizing и завершается completed либо failed (файл не прошёл проверку), expired (не уложились в срок) или cancelled после cancelling.
6. Результаты забираются по идентификатору выходного файла, а ошибки отдельных запросов лежат в файле ошибок.

Среди доступных эндпоинтов в руководстве названы /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations и запросы к изображениям. Заявленные плюсы: скидка 50% к синхронным ценам, отдельные и существенно более высокие лимиты и выполнение в течение 24 часов, часто быстрее. Есть лимиты на пакет: по руководству, до 50 000 запросов и до 200 МБ на входной файл.

Пример строки входного файла:

{"custom_id": "doc-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "<модель>", "messages": [{"role": "user", "content": "Классифицируй текст..."}], "max_tokens": 200}}

Как это устроено у Anthropic

У Anthropic это Message Batches API. По документации: пакет ограничен 100 000 запросов или 256 МБ, большинство пакетов завершается быстрее часа, но пакет истекает, если не завершился за 24 часа, результаты хранятся 29 дней, а цена составляет 50% от обычной. Потоковая отдача (stream: true) в пакетах не поддерживается. Для пакетов с общим контекстом документация советует использовать кэширование с длительностью один час, потому что обработка может занять дольше пяти минут.

Когда пакетный режим выгоден

• Результат не нужен прямо сейчас: ночные отчёты, разметка датасета, классификация архива.
• Запросов много, и вы упираетесь в лимиты скорости обычного API.
• Задача оценивается в деньгах, а не в задержке: оценка моделей на наборе тестов, массовая переработка текстов.

Не подходит он там, где пользователь ждёт ответа в чате, где следующий запрос зависит от предыдущего ответа, и где нужен потоковый вывод.

Чем заменить через шлюз

В перечне эндпоинтов шлюза Zukko (чат-запросы в форматах OpenAI и Anthropic, /v1/responses, список моделей, подсчёт токенов) пакетного эндпоинта нет, поэтому планируйте обработку обычными запросами. Эффект «много и дёшево» получается из трёх приёмов.

1. Параллельные запросы с ограничением. Запускайте несколько запросов одновременно, но не бесконечно: число одновременных запросов держите в пределах, которые выдерживает модель. Ошибки 429 и 503 повторяйте с паузой.
2. Дешёвая модель. Для разметки и классификации начните с модели из нижней части таблицы и проверьте её на выборке из ваших данных; к более дорогой переходите, только если дешёвая не справилась.
3. Кэш общего префикса. Если во всех запросах одинаковая длинная инструкция, её чтение из кэша стоит дешевле входа. Для Claude это работает в Anthropic-формате, для GPT кэш виден в обоих форматах. Подробнее в документации по лимитам и кэшу↗.

Пример скелета на Python с ограничением параллелизма и повтором при перегрузке:

import asyncio
from openai import AsyncOpenAI, APIStatusError

client = AsyncOpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_ваш_ключ")
sem = asyncio.Semaphore(8)  # не больше 8 запросов одновременно

async def classify(doc_id: str, text: str):
    async with sem:
        for attempt in range(4):
            try:
                r = await client.chat.completions.create(
                    model="deepseek-v4.1-flash",
                    messages=[
                        {"role": "system", "content": "Ответь одним словом: тема текста."},

Роль custom_id здесь играет ключ словаря: результат всегда связан с исходным документом. Развёрнутую версию с повторами и учётом расходов смотрите в статье асинхронные запросы в Python↗, а про разбор ошибок — в статье retry, 429 и 503↗.

Сравнение по деньгам

Допустим, нужно обработать 10 000 документов, по 1000 токенов входа и 200 токенов выхода на каждый. Итого 10 млн токенов входа и 2 млн токенов выхода. Цены на 18 октября 2026, кэш не учитывается.

Официальный пакетный режим берёт 50% от обычной цены поставщика (по документации поставщиков). Для claude-sonnet-5-5 обычная официальная цена в нашей таблице 2 / 10 за миллион:

• обычный режим: 10 × 2 + 2 × 10 = 20 + 20 = $40;
• пакетный режим по цене 50%: $20.

Через шлюз по обычным запросам, цены Zukko:

• claude-sonnet-5-5 (0,4 / 2): 10 × 0,4 + 2 × 2 = 4 + 4 = $8;
• gpt-6.1-sol (0,27 / 1,32): 10 × 0,27 + 2 × 1,32 = 2,7 + 2,64 = $5,34;
• deepseek-v4.1-flash (0,013 / 0,038): 10 × 0,013 + 2 × 0,038 = 0,13 + 0,076 = $0,206.

Выводы стоит делать осторожно. Эти числа сравнивают разные вещи: пакетная скидка относится к официальным ценам, а цены Zukko ниже официальных сами по себе. К тому же вы платите за пополнение комиссией платёжной страницы (СБП добавляет 8,5% сверху), а качество разных моделей на вашей задаче разное. Выбирайте модель по выборке из ваших данных, а не по таблице.

Актуальный список и цены: GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Частые вопросы

Batch API дешевле обычного?

У OpenAI и Anthropic да, по документации скидка 50% к обычным ценам, взамен результат приходит в течение суток. Отдельной скидки на шлюзе за пакеты нет: преимущество там даёт низкая цена токена и кэш.

Есть ли пакетный режим у шлюза Zukko?

В документации шлюза пакетного эндпоинта нет. Используйте параллельные запросы с ограничением, как в примере выше.

Можно ли получить результат сразу?

Не в пакетном режиме. Если нужен быстрый ответ, отправляйте обычные запросы.

Как не упереться в лимиты при массовой обработке?

Ограничьте параллелизм, повторяйте 429 и 503 с паузой и разделите работу на несколько ключей с дневными лимитами. Подробно — в статье массовая обработка без упора в лимит↗. Ключ создаётся в кабинете↗; доступ из России — через шлюз, оплата СБП, картой MasterCard или криптой.