Пакетная обработка

Когда запросов много, а ответ нужен не сию секунду, их выгоднее отправить пакетом. Запросы уходят одной пачкой, обрабатываются в течение суток и стоят вдвое дешевле обычных. Подходит для разовой обработки массива данных: разметить архив обращений, посчитать эмбеддинги для базы знаний, перевести каталог товаров.

Три формата — три механизма

Здесь единого способа нет: у каждого формата свой эндпоинт и своя форма запроса, и запросы между ними не переводятся. Выбирать нужно тот, который соответствует модели.

Формат OpenAI

Единственный из трёх, где запросы передаются файлом. Формат файла — JSONL: одна строка на запрос, без запятых между строками.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-5-mini", "messages": [{"role": "user", "content": "Тема обращения: не пришёл заказ"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-5-mini", "messages": [{"role": "user", "content": "Тема обращения: хочу вернуть товар"}]}}

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

Файл загружается с назначением batch — других назначений здесь нет. В форме purpose должен идти перед файлом:

curl "https://api.proxyapi.ru/v1/files" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    -F "purpose=batch" \
    -F "file=@requests.jsonl"

Полученный идентификатор файла передаётся при создании пакета:

curl "https://api.proxyapi.ru/v1/batches" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    -d '{
        "input_file_id": "file-abc123",
        "endpoint": "/v1/chat/completions",
        "completion_window": "24h"
    }'

Поле endpoint должно совпадать с адресом в строках файла: смешивать в одном пакете запросы к разным эндпоинтам нельзя. Доступны три эндпоинта — /v1/chat/completions, /v1/responses и /v1/embeddings.

Состояние пакета запрашивается по его идентификатору: нужно дождаться, пока status не станет completed. Тогда в ответе появляется output_file_id — по нему скачиваются результаты:

curl "https://api.proxyapi.ru/v1/batches/batch-abc123" \
    -H "Authorization: Bearer <КЛЮЧ>"

curl "https://api.proxyapi.ru/v1/files/file-def456/content" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    --output results.jsonl

Незавершённый пакет снимается запросом POST /v1/batches/batch-abc123/cancel.

Формат Anthropic

Здесь файл не нужен: запросы перечисляются прямо в теле. У каждого свой custom_id, а само тело обычного запроса лежит в params.

curl "https://api.proxyapi.ru/v1/messages/batches" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: <КЛЮЧ>" \
    -d '{
        "requests": [
            {
                "custom_id": "req-1",
                "params": {
                    "model": "anthropic/claude-haiku-4-5",
                    "max_tokens": 256,
                    "messages": [{"role": "user", "content": "Тема обращения: не пришёл заказ"}]
                }
            }
        ]
    }'

Готовность видна в поле processing_status: пакет закончен, когда там оказывается ended. Результаты лежат на отдельном адресе и приходят построчно, по строке на запрос:

curl "https://api.proxyapi.ru/v1/messages/batches/msgbatch_abc/results" \
    -H "X-API-Key: <КЛЮЧ>" \
    --output results.jsonl

Отмена — POST /v1/messages/batches/msgbatch_abc/cancel. Работает всё это только с моделями Anthropic.

Формат Google

Модель указывается в самом адресе, запросы — списком внутри input_config. Роль custom_id здесь играет произвольное поле metadata.

curl "https://api.proxyapi.ru/v1beta/models/gemini-2.5-flash:batchGenerateContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: <КЛЮЧ>" \
    -d '{
        "batch": {
            "display_name": "Разбор обращений",
            "input_config": {
                "requests": {
                    "requests": [
                        {
                            "request": {
                                "contents": [{"parts": [{"text": "Тема обращения: не пришёл заказ"}]}]
                            },
                            "metadata": {"key": "req-1"}
                        }
                    ]
                }
            }
        }
    }'

В ответе приходит имя пакета вида batches/abc123 и его состояние в поле state. Для опроса из имени берётся только идентификатор, без приставки batches/:

curl "https://api.proxyapi.ru/v1beta/batches/abc123" \
    -H "x-goog-api-key: <КЛЮЧ>"

Отдельного адреса для результатов здесь нет: когда state переходит в завершённое состояние, ответы приходят прямо в объекте пакета, а сопоставляются с запросами по переданному metadata.

Отмена — POST /v1beta/batches/abc123:cancel. Пакетами обрабатываются только текстовые модели Google.

Общее для всех трёх

Баланс проверяется на запуске. Он должен покрывать оценочную стоимость всего пакета с запасом, иначе приходит ошибка 402 и пакет не создаётся.

Неудачный запрос не роняет пакет. В его строке результата будет ошибка, соседние отработают как обычно.

Цена вдвое ниже. И входные, и выходные токены тарифицируются по половинной цене, списание — по факту выполнения, а не при запуске.

Время — плата за скидку. Пакет выполняется в пределах суток, повлиять на очередь нельзя. Если ответ нужен сразу, это не тот инструмент.

Что дальше

• Генерация текста — устройство запросов, из которых собирается пакет.
• Эмбеддинги — самая частая задача для пакетной обработки.