Быстрый старт Batch API

Batch API позволяет отправить множество инференс-запросов одним пакетом и забрать результаты асинхронно. Он удобен для задач, которым не нужен немедленный ответ: на выполнение отводится окно в 24 часа, и вам не нужно управлять каждым вызовом по отдельности. Batch API поддерживает несколько форм API LLMSTORE: chat completions, Responses и Anthropic Messages. Запросы передаются инлайн-массивом requests в JSON. Загружать JSONL-файл не нужно — хранение JSONL LLMSTORE берёт на себя.

Результаты пакета доступны асинхронно. Успешная отправка возвращает 202 Accepted со статусом status: "validating" — это значит, что пакет сохранён и поставлен в очередь на валидацию, а не что все запросы уже выполнены.

Ограничения

Batch API сейчас работает только с текстом. На /v1/chat/completions, /v1/responses и /v1/messages запрос с контентом типа image, audio, video или file отклоняется на валидации — включая части input_image и input_file в Responses и блоки image и document в Anthropic. На /v1/chat/completions также отклоняется запрос нетекстового вывода через modalities, audio или image_config. Для embeddings input должен быть строками или массивами токенов. Мультимодальные запросы отправляйте в синхронный API.

Цены

Запросы через Batch API обычно тарифицируются по 50% от стандартной потокенной цены модели — аналогично скидкам за batch у OpenAI и Anthropic. Для завершённого пакета usage.cost показывает сумму, списанную LLMSTORE; для пакетов, маршрутизированных через BYOK, это только комиссия BYOK, потому что инференс у провайдера оплачивается напрямую.

Нетокенные составляющие цены скидкой не покрываются единообразно: например, вызовы веб-поиска тарифицируются по стандартным ставкам, а цены кэширования промптов зависят от модели — источник истины по ценам встроен в наш справочник моделей. Метаданные моделей доступны через GET /v1/models.

Отправка пакета

Отправка пакета:

Эндпоинт

POST https://api.llmstore.ru/beta/batches

В теле запроса три обязательных поля верхнего уровня:

Поле	Описание
`endpoint`	Форма API, которую использует каждый запрос пакета. Одно из: `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`.
`model`	Слаг модели LLMSTORE, например `openai/gpt-4o`. Эта модель уровня пакета применяется ко всем запросам.
`requests`	Непустой массив элементов `{ custom_id, body }`. `custom_id` должен быть уникален внутри пакета, а `body` соответствует форме выбранного `endpoint`.

Сериализуйте endpoint и model раньше requests в JSON-теле. API разбирает запрос потоково, чтобы принимать очень большие массивы requests без буферизации, и вернёт 400, если requests идёт первым. Все примеры на этой странице уже используют правильный порядок.

model уровня пакета применяется ко всем запросам. Тело запроса может опустить model — тогда наследуется значение пакета. Если тело задаёт свою model, она должна совпадать с моделью пакета, иначе отправка отклоняется. Для моделей Google все запросы пакета должны требовать один и тот же response_format: либо все опускают его, либо все используют json_object, либо все используют json_schema с одинаковой схемой. Batch-сервис Google выводит одну выходную схему на весь пакет, поэтому несогласованные запросы падают там. Несогласованный пакет отклоняется на валидации с указанием первого конфликтующего запроса — отправляйте отдельный пакет на каждый response_format и каждую схему.

import json
import requests

response = requests.post(
  url="https://api.llmstore.ru/beta/batches",
  headers={
    "Authorization": "Bearer <LLMSTORE_API_KEY>",
    "Content-Type": "application/json",
  },
  data=json.dumps({
    "endpoint": "/v1/chat/completions",
    "model": "openai/gpt-4o",
    "requests": [
      {
        "custom_id": "req-0001",
        "body": {
          "messages": [
            {
              "role": "user",
              "content": "Summarize LLMSTORE in one sentence."
            }
          ]
        }
      }
    ]
  })
)

print(response.json())

const response = await fetch('https://api.llmstore.ru/beta/batches', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <LLMSTORE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    endpoint: '/v1/chat/completions',
    model: 'openai/gpt-4o',
    requests: [
      {
        custom_id: 'req-0001',
        body: {
          messages: [
            {
              role: 'user',
              content: 'Summarize LLMSTORE in one sentence.',
            },
          ],
        },
      },
    ],
  }),
});

console.log(await response.json());

curl https://api.llmstore.ru/beta/batches \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LLMSTORE_API_KEY" \
  -d '{
  "endpoint": "/v1/chat/completions",
  "model": "openai/gpt-4o",
  "requests": [
    {
      "custom_id": "req-0001",
      "body": {
        "messages": [
          {
            "role": "user",
            "content": "Summarize LLMSTORE in one sentence."
          }
        ]
      }
    }
  ]
}'

Ответ — объект пакета с ID, по которому можно отслеживать прогресс:

202 Accepted

{
  "id": "batch_123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "model": "openai/gpt-4o",
  "completion_window": "24h",
  "status": "validating",
  "created_at": 1782097200,
  "finalized_at": null,
  "request_counts": {
    "total": 1,
    "completed": 0,
    "failed": 0
  },
  "usage": null,
  "results": null,
  "error": null
}

Единственное поддерживаемое окно выполнения — 24h.

Опрос результатов

По ID пакета запрашивается текущий статус:

Эндпоинт

GET https://api.llmstore.ru/beta/batches/:id

Например:

Shell

curl https://api.llmstore.ru/beta/batches/batch_123 \
  -H "Authorization: Bearer $LLMSTORE_API_KEY"

Обычно статус проходит цепочку:

Смена статусов

validating → in_progress → finalizing → completed

Другие возможные статусы: failed, expired, cancelling и cancelled. Терминальные статусы — completed, failed, expired и cancelled. Опрашивайте, пока пакет не достигнет терминального статуса. request_counts содержит общее число запросов и сколько из них завершилось или упало:

request_counts

{
  "total": 100,
  "completed": 98,
  "failed": 2
}

Пока пакет выполняется, а также если он упал, истёк или отменён, results равен null. Когда пакет завершается, results возвращается инлайн массивом в том же ответе. Отдельного эндпоинта для скачивания результатов нет. Каждый результат сопоставляется со входным запросом по custom_id. Ровно одно из полей response или error заполнено в каждом результате:

Элемент результата

{
  "id": "batch_req_123",
  "custom_id": "req-0001",
  "response": {
    "status_code": 200,
    "request_id": "request_123",
    "body": {
      "id": "gen-batch-1782097200-a1b2c3d4e5f6a7b8c9d0",
      "object": "chat.completion",
      "created": 1782097200,
      "model": "openai/gpt-4o",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "LLMSTORE provides one API for many AI models."
          },
          "finish_reason": "stop"
        }
      ]
    }
  },
  "error": null
}

Ответ завершённого пакета выглядит так:

Завершённый пакет

{
  "id": "batch_123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "model": "openai/gpt-4o",
  "completion_window": "24h",
  "status": "completed",
  "created_at": 1782097200,
  "finalized_at": 1782100800,
  "request_counts": {
    "total": 1,
    "completed": 1,
    "failed": 0
  },
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 40,
    "total_tokens": 60,
    "cost": 0.000225,
    "is_byok": false
  },
  "results": [
    {
      "id": "batch_req_123",
      "custom_id": "req-0001",
      "response": {
        "status_code": 200,
        "request_id": "request_123",
        "body": {
          "id": "gen-batch-1782097200-a1b2c3d4e5f6a7b8c9d0",
          "object": "chat.completion",
          "created": 1782097200,
          "model": "openai/gpt-4o",
          "choices": [
            {
              "index": 0,
              "message": {
                "role": "assistant",
                "content": "LLMSTORE provides one API for many AI models."
              },
              "finish_reason": "stop"
            }
          ]
        }
      },
      "error": null
    }
  ],
  "error": null
}

Жалобы на генерации

response.body.id каждого завершённого результата — это ID генерации LLMSTORE для этого запроса (например gen-batch-...). Чтобы пожаловаться на плохую генерацию, скопируйте этот ID и отправьте его через Report Feedback, выбрав сценарий By generation ID.

Фидбек по генерациям доступен для форм /v1/chat/completions, /v1/responses и /v1/messages.

Разные формы API

Верхнеуровневое поле endpoint выбирает форму запроса, которую использует каждый body пакета. Поддерживаемые формы:

Chat completions: /v1/chat/completions
Responses: /v1/responses
Anthropic Messages: /v1/messages

Например, пакет Anthropic Messages использует /v1/messages, а в body каждого элемента кладётся запрос в форме Messages:

Пакет Anthropic Messages

{
  "endpoint": "/v1/messages",
  "model": "anthropic/claude-3.5-sonnet",
  "requests": [
    {
      "custom_id": "req-1",
      "body": {
        "max_tokens": 32,
        "messages": [
          {
            "role": "user",
            "content": "Say hello."
          }
        ]
      }
    }
  ]
}

Все запросы одного пакета используют один и тот же верхнеуровневый endpoint. Чтобы смешивать формы API, отправляйте отдельные пакеты.

Эмбеддинги

Эмбеддинги постепенно появляются у провайдеров, которые их поддерживают. Установите верхнеуровневый endpoint в /v1/embeddings и кладите запрос эмбеддингов в body каждого элемента. Каждый body принимает input (строка, массив строк, массив токенов или массив массивов токенов). Мультимодальные входы, input_type и предпочтения provider в Batch API не поддерживаются — для этого используйте синхронный API. input может быть одной строкой или массивом строк. Если это массив, запрос эмбеддит все строки за один вызов:

Пакет эмбеддингов

{
  "endpoint": "/v1/embeddings",
  "model": "openai/text-embedding-3-small",
  "requests": [
    {
      "custom_id": "emb-0001",
      "body": {
        "input": [
          "The quick brown fox jumped over the lazy dog.",
          "Pack my box with five dozen liquor jugs."
        ]
      }
    },
    {
      "custom_id": "emb-0002",
      "body": {
        "input": "The quick brown fox jumped over the lazy dog."
      }
    }
  ]
}

Опрос результатов — как у любого другого пакета (GET https://api.llmstore.ru/beta/batches/:id). Ниже — элементы массива results завершённого пакета (показан полностью выше); каждый несёт стандартный ответ эмбеддингов в своём body, и на каждый custom_id приходится один элемент. Запрос, чей input — массив строк, возвращает по одному объекту эмбеддинга на строку в data (упорядочены по index); запрос с одной строкой возвращает ровно один:

Результаты эмбеддингов

[
  {
    "id": "batch_req_emb_1",
    "custom_id": "emb-0001",
    "response": {
      "status_code": 200,
      "request_id": "request_456",
      "body": {
        "object": "list",
        "data": [
          {
            "object": "embedding",
            "embedding": [0.0023064255, -0.009327292, 0.015797347],
            "index": 0
          },
          {
            "object": "embedding",
            "embedding": [-0.012282, 0.0034567, -0.0089123],
            "index": 1
          }
        ],
        "model": "openai/text-embedding-3-small",
        "usage": {
          "prompt_tokens": 18,
          "total_tokens": 18
        }
      }
    },
    "error": null
  },
  {
    "id": "batch_req_emb_2",
    "custom_id": "emb-0002",
    "response": {
      "status_code": 200,
      "request_id": "request_789",
      "body": {
        "object": "list",
        "data": [
          {
            "object": "embedding",
            "embedding": [0.0023064255, -0.009327292, 0.015797347],
            "index": 0
          }
        ],
        "model": "openai/text-embedding-3-small",
        "usage": {
          "prompt_tokens": 8,
          "total_tokens": 8
        }
      }
    },
    "error": null
  }
]

Входы и результаты пакетов хранятся как JSONL-артефакты и автоматически удаляются через 30 дней после создания — в соответствии с окном хранения у вышестоящих провайдеров. Скачайте нужные результаты до истечения 30-дневного окна.

Начало работы

Аутентификация

Мультимодальность

Модели и роутинг

Варианты моделей

Возможности

Плагины

Администрирование

Приватность

Лучшие практики

SDK и интеграции

Ограничения

Цены

Отправка пакета

Опрос результатов

Жалобы на генерации

Разные формы API

Эмбеддинги

​Ограничения

​Цены

​Отправка пакета

​Опрос результатов

​Жалобы на генерации

​Разные формы API

​Эмбеддинги

Ограничения

Цены

Отправка пакета

Опрос результатов

Жалобы на генерации

Разные формы API

Эмбеддинги