Документация Пакетная обработка Batches

Batch API

Отправка и получение асинхронных пакетов (batch) inference-запросов.

Batch API позволяет отправлять множество inference-запросов вместе и получать результаты асинхронно. Подходит для задач, не требующих мгновенного ответа. Использует 24-часовое окно выполнения — вы можете обрабатывать запросы, не управляя каждым вызовом по отдельности.

Batch API поддерживает несколько форм-факторов API: chat completions, Responses и Anthropic Messages. Запросы передаются в виде встроенного JSON-массива requests.

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

Эндпоинт

POST https://api.ru-openrouter.ru/v1/batches
GET  https://api.ru-openrouter.ru/v1/batches/{batch_id}

Создание батча

Тело запроса

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

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

Модель, указанная на уровне батча (model), применяется ко всем запросам. Отдельный запрос может опустить model, чтобы унаследовать значение батча. Если запрос указывает свою model, она должна совпадать с моделью батча, иначе отправка будет отклонена.

Пример

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

import json
import requests

response = requests.post(
    url="https://api.ru-openrouter.ru/v1/batches",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "endpoint": "/v1/chat/completions",
        "model": "google/gemini-3.1-flash-lite:batch",
        "requests": [
            {
                "custom_id": "req-0001",
                "body": {
                    "messages": [
                        {
                            "role": "user",
                            "content": "Summarize OpenRouter in one sentence."
                        }
                    ]
                }
            }
        ]
    })
)

print(response.json())

const response = await fetch('https://api.ru-openrouter.ru/v1/batches', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer ',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        endpoint: '/v1/chat/completions',
        model: 'google/gemini-3.1-flash-lite:batch',
        requests: [
            {
                custom_id: 'req-0001',
                body: {
                    messages: [
                        {
                            role: 'user',
                            content: 'Summarize OpenRouter in one sentence.',
                        },
                    ],
                },
            },
        ],
    }),
});

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

Ответ (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
}

Опрос статуса

Используйте ID батча для получения текущего статуса:

curl https://api.ru-openrouter.ru/v1/batches/batch_123 \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Результаты завершённых батчей (статусы completed, failed, expired, cancelled) возвращаются в этом же ответе.

Последовательность статусов

validating → in_progress → finalizing → completed

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

Статусы cancelling и cancelled приходят от вышестоящего провайдера, когда отмена батча инициирована на их стороне. Отмена запущенного батча через данный API в настоящее время не поддерживается.

Счётчик запросов

{
  "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": "OpenRouter 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.45
  },
  "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": "OpenRouter provides one API for many AI models."
              },
              "finish_reason": "stop"
            }
          ]
        }
      },
      "error": null
    }
  ],
  "error": null
}

Список батчей

Получите список своих батчей, опустив ID батча:

curl "https://api.ru-openrouter.ru/v1/batches?limit=20" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`limit`	`integer`	`20`	Максимальное количество батчей в ответе (макс. 20).

Ответ

{
  "object": "list",
  "data": [
    {
      "id": 1,
      "user_id": 42,
      "batch_id": "batch_123",
      "endpoint": "/v1/chat/completions",
      "model": "openai/gpt-4o",
      "status": "completed",
      "created_at": "2025-06-15 10:00:00"
    }
  ]
}

Поддерживаемые формы-факторы API

Укажите endpoint на верхнем уровне, чтобы выбрать форму-фактор для всех body в батче:

Форма-фактор	Значение `endpoint`
Chat completions	`/v1/chat/completions`
Responses	`/v1/responses`
Embeddings	`/v1/embeddings`

Пример: chat/completions

{
  "endpoint": "/v1/chat/completions",
  "model": "google/gemini-3.1-flash-lite:batch",
  "requests": [
    {
      "custom_id": "req-000123",
      "body": {
        "max_tokens": 1000,
        "messages": [
          {
            "role": "user",
            "content": "Привет как дела?"
          }
        ]
      }
    }
  ]
}

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

Embeddings

Установите endpoint в /v1/embeddings и передайте запросы на эмбеддинги в каждом body. Каждый body принимает input (строка, массив строк, массив токенов или массив массивов токенов).

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 /v1/batches/{batch_id}). Каждый элемент массива results содержит стандартный ответ эмбеддингов в своём body, по одному результату на custom_id. Если input был массивом строк — в data возвращается несколько объектов эмбеддингов (упорядоченных по index); для одного input возвращается ровно один:

[
  {
    "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
  }
]

Мультимодальные входные данные, input_type и настройки provider не поддерживаются в Batch API. Используйте синхронный API для этих возможностей.

Хранение данных

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