Batch API: пакетная обработка запросов

Батч выполняет набор независимых запросов в фоне. Загрузите файл один раз, сохраните ID задания и скачайте готовые ответы позже. Такой режим подходит для классификации, разметки и извлечения данных, когда мгновенный ответ не нужен.

Тариф

Оптимальный

Окно обработки

24 часа с создания

Результаты

29 дней с создания

Перейти к запуску → · Посмотреть цены моделей →

Цена с наценкой Оптимального

В карточке модели найдите отдельный блок «Батч»: в нём показаны вход и выход за 1 млн токенов. Наценка Оптимального уже учтена в этих ставках; скидка компании, если она есть, применяется один раз. Наличие обычной цены не означает доступность батча.

У батча может быть собственная база. Коэффициент ×0,5 применяется к ней, поэтому сравнивайте готовые ставки, а не делите цену обычного API пополам.

Цена батча = базовая цена батч-обработки
           × наценка Оптимального
           × коэффициент батча
           × (1 − скидка компании / 100), если она есть

Какие модели доступны

Текущий профиль Batch API поддерживает qwen3.7-plus, qwen-max, qwen-plus и qwen-flash. Поддержка профилем ещё не означает, что модель сейчас опубликована для батчей. Перед отправкой проверьте живой каталог GET /api/pricing:

curl -sS https://neuroapi.host/api/pricing \
  | jq '.data.models[]
    | select(.model_name as $model
      | ["qwen3.7-plus", "qwen-max", "qwen-plus", "qwen-flash"] | index($model))
    | select((.batch_enable_groups // []) | index("plus"))
    | {model_name, batch_enable_groups, batch_tariff_multiplier, batch_pricing}'

Модель должна содержать plus в batch_enable_groups. Поле enable_groups отдельно описывает обычные синхронные запросы: наличие модели там не доказывает поддержку батча. Используйте API-ключ Оптимального; Смарт не является отдельным физическим тарифом для создания этого батча.

1. Подготовьте JSONL

Файл — UTF-8 JSONL: один объект запроса на строку. Все строки используют одну модель. custom_id уникален внутри файла и помогает сопоставить ответ с запросом.

{"custom_id":"classification-1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.7-plus","messages":[{"role":"system","content":"Классифицируй обращение: вопрос, отзыв или жалоба. Верни одно слово."},{"role":"user","content":"Как скачать историю запросов?"}],"enable_thinking":false,"max_tokens":32}}
{"custom_id":"classification-2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.7-plus","messages":[{"role":"system","content":"Классифицируй обращение: вопрос, отзыв или жалоба. Верни одно слово."},{"role":"user","content":"Спасибо за удобный кабинет!"}],"enable_thinking":false,"max_tokens":32}}

Поддерживается только method: "POST" и url: "/v1/chat/completions". Текущий профиль принимает текстовые сообщения system, user, assistant; content должен быть строкой. Инструменты, поиск, hosted tools, медиа, потоковая передача (stream: true) и режим размышлений не поддерживаются. Не добавляйте tools, response_format, thinking_budget или неизвестные поля: неподдерживаемые параметры отклоняются, а не игнорируются.

Обязательно задайте один положительный лимит ответа: max_tokens либо, только для qwen3.7-plus, max_completion_tokens. Оба поля одновременно запрещены. Для qwen3.7-plus укажите enable_thinking: false; true отклоняется для всех моделей этого профиля. Параметры запроса находятся непосредственно в body, без оболочки extra_body.

Оценка входа, лимит ответа и запас 10 токенов вместе должны помещаться в контекст модели. Для батча qwen3.7-plus окно ограничено 256 000 токенами, даже если обычный API допускает больше. При проверке длины используется консервативная оценка: фактическое списание рассчитывается по подтверждённому использованию, а не по этой оценке.

Размеры и число строк

Лимиты строки и файла проверяются до и после нормализации JSON. Экранирование может увеличить размер; в размер нормализованного файла входит перевод строки после каждого запроса.

Для каждой строки заранее учитывается бюджет:

8 КиБ + 2048 × (лимит выходных токенов + 10) байт

Сумма по всем строкам не должна превышать 512 МиБ. Это защитный бюджет хранения, он не является ценой и не списывается с баланса. Слишком большой max_tokens уменьшает допустимое число строк: задавайте предел под задачу и делите большие наборы на несколько файлов. У одного пользователя или компании также может быть настроен лимит незавершённых запросов в очереди.

2. Загрузите файл

Сохраните JSONL в requests.jsonl. Передайте API-ключ только через защищённое окружение и загрузите файл с purpose=batch:

export NEUROAPI_KEY='ВАШ_API_КЛЮЧ_ОПТИМАЛЬНОГО'

curl -sS https://neuroapi.host/v1/files \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -F purpose=batch \
  -F file=@requests.jsonl

Из ответа сохраните id, например file-.... Используйте тот же ключ для доступа к загруженному файлу. Загрузка файла сама по себе не запускает обработку.

3. Создайте батч

curl -sS https://neuroapi.host/v1/batches \
  -H "Authorization: Bearer $NEUROAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: classification-2026-10-22-01" \
  -d '{
    "input_file_id": "file-ИЗ-ОТВЕТА-ЗАГРУЗКИ",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"dataset": "support-classification"}
  }'

Поддерживается completion_window: "24h". metadata необязательно: до 16 пар, ключ 1–64 символа, значение до 512 символов. Не помещайте туда секреты. Общий JSON создания ограничен 16 КиБ, включая metadata.

Сохраните возвращённый id вида batch_.... Ответ содержит status, request_counts, временные отметки, output_file_id и error_file_id. Поля файлов остаются null, пока соответствующие результаты недоступны.

Если потерялся ответ создания

Всегда задавайте уникальный Idempotency-Key для нового задания. При сетевом сбое повторите тот же запрос с тем же ключом и тем же телом. Принятый батч вернётся повторно без создания нового задания. Изменённое тело с тем же ключом конфликтует. Тело сравнивается побайтово: сохраняйте исходный JSON, включая пробелы и порядок полей. Максимальная длина Idempotency-Key после удаления пробелов по краям — 255 байт. Новый ключ означает новое задание и может привести к повторной платной обработке. Не загружайте файл заново только из-за потери ответа создания. Защита повторного создания действует, пока сохраняется заголовок задания. После его удаления повтор старого ключа больше не гарантирует возврат исходного батча: не используйте старые ключи для автоматического восстановления.

4. Проверяйте статус

curl -sS "https://neuroapi.host/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $NEUROAPI_KEY"

Сначала сохраните ID в BATCH_ID. Опрашивайте с умеренной частотой, например раз в 10–30 секунд; при временных ошибках увеличивайте интервал.

request_counts.total — число запросов, completed — успешные, failed — завершившиеся без успешного ответа. Статус completed не гарантирует успех каждой строки: всегда проверяйте счётчики и файл ошибок. expires_at обозначает конец окна обработки, а не срок хранения результатов.

Список заданий доступен через GET /v1/batches?limit=20. Для следующей страницы передайте after из last_id, если has_more: true; limit принимает 1–100.

5. Скачайте результаты и ошибки

После завершения возьмите output_file_id и error_file_id из ресурса батча. Скачивайте каждый файл, только если его ID не null:

curl -sS "https://neuroapi.host/v1/files/$OUTPUT_FILE_ID/content" \
  -H "Authorization: Bearer $NEUROAPI_KEY" -o output.jsonl

curl -sS "https://neuroapi.host/v1/files/$ERROR_FILE_ID/content" \
  -H "Authorization: Bearer $NEUROAPI_KEY" -o errors.jsonl

Успешная строка содержит обычный ответ Chat Completions внутри response.body:

{
  "id": "batch_req_123",
  "custom_id": "classification-1",
  "response": {
    "status_code": 200,
    "request_id": "...",
    "body": {
      "choices": [{"index": 0, "message": {"role": "assistant", "content": "вопрос"}}],
      "usage": {"prompt_tokens": 100, "completion_tokens": 1, "total_tokens": 101}
    }
  },
  "error": null
}

Ошибка строки содержит response: null и объект error с code и русским message. Порядок результатов может отличаться от входного: связывайте строки исключительно по custom_id. Сохраняйте собственную карту исходных запросов. Для повторной отправки создавайте новый файл только с теми строками, чья ошибка подтверждена; не переотправляйте целый батч из-за одного неуспешного запроса.

Файлы результатов доступны только владельцу задания. После истечения 29 дней от создания их содержимое удаляется, а output_file_id и error_file_id больше не выдаются. Собственная своевременная выгрузка обязательна для долгого хранения.

Сроки обработки и хранения

Окно обработки — 24 часа с момента создания. Это срок выполнения задания, а не срок доступа к ответам: expires_at обозначает именно конец обработки.

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

Отмена

curl -sS -X POST "https://neuroapi.host/v1/batches/$BATCH_ID/cancel" \
  -H "Authorization: Bearer $NEUROAPI_KEY"

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

Ошибки и безопасное восстановление

Если задание уже принято и его исход остаётся неизвестным, проверяйте сохранённый ID. Сам по себе таймаут не доказывает, что обработка не началась. При длительной неопределённости обратитесь в поддержку, передав ID батча и время создания без API-ключа.

Краткая схема API

Цены моделей · Тарифы и наценки · Общие ошибки API