Перейти к содержимому
MGModel Gate
ВойтиНачать работу

OpenAI-совместимый Batch API

Загрузка входных JSONL-файлов и выполнение OpenAI-совместимых пакетов через устойчивую очередь Model Gate.

Model Gate реализует последовательность OpenAI Files + Batch на https://api.model-gate.com/v1. Это слой совместимости: каждая строка JSONL выполняется через обычный путь инференса Model Gate. Model Gate не отправляет пакет в собственный OpenAI Batch API поставщика.

С действующим активным API-ключом можно перечислять, читать, скачивать, отменять и удалять свои существующие ресурсы Files/Batch даже при нулевом балансе или исчерпанном обнуляемом лимите расходов. Загрузка файлов и создание пакетов требуют положительного баланса и доступного лимита расходов. Каждый элемент также должен соответствовать текущим ограничениям в момент запуска. Для сохраняемого объёма, файлов, активных заданий и элементов очереди действуют отдельные квоты; загрузка может быть отклонена даже при наличии средств.

В этом выпуске поддерживаются следующие пакетные эндпоинты:

  • /v1/responses
  • /v1/chat/completions
  • /v1/embeddings

Для каждого выполненного элемента записываются request_mode=batch, batch_protocol=openai, а также его batch_job_public_id и custom_id.

1. Загрузить входной JSONL-файл

Каждая непустая строка содержит custom_id, method, url и body. URL должен совпадать с эндпоинтом, который затем передаётся в /v1/batches.

Пример batch.jsonl:

{"custom_id":"request-1","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.4","input":"Summarize this text."}}
{"custom_id":"request-2","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.4","input":"Classify this text."}}

Запрос

curl https://api.model-gate.com/v1/files \
  -H "Authorization: Bearer mg_live_..." \
  -F "purpose=batch" \
  -F "file=@batch.jsonl"

Ответ — 200

{
  "id": "file-01K...",
  "object": "file",
  "bytes": 322,
  "created_at": 1786610000,
  "filename": "batch.jsonl",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

2. Создать пакет

completion_window должно иметь значение 24h.

Запрос

curl https://api.model-gate.com/v1/batches \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id":"file-01K...",
    "endpoint":"/v1/responses",
    "completion_window":"24h",
    "metadata":{"job":"nightly-evaluation"}
  }'

Ответ — 200

{
  "id": "batch_01K...",
  "object": "batch",
  "endpoint": "/v1/responses",
  "input_file_id": "file-01K...",
  "completion_window": "24h",
  "status": "in_progress",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "job": "nightly-evaluation"
  }
}

3. Получить пакет

Запрос

curl https://api.model-gate.com/v1/batches/batch_01K... \
  -H "Authorization: Bearer mg_live_..."

Ответ — завершено

{
  "id": "batch_01K...",
  "object": "batch",
  "endpoint": "/v1/responses",
  "status": "completed",
  "output_file_id": "file-01KOUTPUT...",
  "error_file_id": null,
  "request_counts": {
    "total": 2,
    "completed": 2,
    "failed": 0
  },
  "usage": {
    "input_tokens": 240,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 90,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 330
  }
}

4. Скачать результаты

Запрос

curl https://api.model-gate.com/v1/files/file-01KOUTPUT.../content \
  -H "Authorization: Bearer mg_live_..."

Ответ — 200

{"id":"batch_req_01K...","custom_id":"request-1","response":{"status_code":200,"request_id":"01K...","body":{"id":"resp_...","status":"completed"}},"error":null}

Элементы, завершившиеся ошибкой, отменённые или просроченные, записываются в error_file_id как JSONL-записи с response:null и объектом error.

5. Получить список пакетов

limit по умолчанию равно 20, допустимый диапазон — от 1 до 100. Для постраничной навигации по курсору используйте after.

Запрос

curl "https://api.model-gate.com/v1/batches?limit=20&after=batch_01K..." \
  -H "Authorization: Bearer mg_live_..."

Ответ — 200

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Завершённые пакетные объекты могут включать сводный объект usage, если доступны завершённые записи учёта запросов Model Gate.

6. Отменить пакет

Отмена не позволяет запустить элементы, оставшиеся в очереди; уже выполняющийся элемент может завершиться.

Запрос

curl -X POST https://api.model-gate.com/v1/batches/batch_01K.../cancel \
  -H "Authorization: Bearer mg_live_..."

Ответ — 200

{
  "id": "batch_01K...",
  "object": "batch",
  "status": "cancelling",
  "request_counts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  }
}

7. Метаданные, список и удаление файлов

Получить метаданные:

curl https://api.model-gate.com/v1/files/file-01K... \
  -H "Authorization: Bearer mg_live_..."
{
  "id": "file-01K...",
  "object": "file",
  "bytes": 322,
  "filename": "batch.jsonl",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1789202000
}

Получить список файлов с необязательными purpose, after и order=asc|desc; limit по умолчанию равно 10000, допустимый диапазон — от 1 до 10000:

curl "https://api.model-gate.com/v1/files?purpose=batch&order=desc&limit=100" \
  -H "Authorization: Bearer mg_live_..."
{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Удалить файл, на который нет ссылок и состояние которого допускает удаление по сроку хранения:

curl -X DELETE https://api.model-gate.com/v1/files/file-01K... \
  -H "Authorization: Bearer mg_live_..."
{
  "id": "file-01K...",
  "object": "file",
  "deleted": true
}

Ограничения и восстановление после сбоев

Model Gate принимает до 50 000 элементов JSONL и ограничивает загружаемый файл настроенным значением OPENAI_BATCH_MAX_FILE_BYTES (по умолчанию 200 МиБ). Каждый отдельный элемент также должен укладываться в обычный лимит Model Gate MAX_REQUEST_BODY_BYTES. Значения custom_id должны быть уникальными. Элементы пакета не могут использовать stream:true или вложенное async:true. Большие JSONL-файлы сохраняются внутри системы частями в БД, а не одним чрезмерно большим SQL-значением.

Выполнение имеет семантику как минимум один раз, а не ровно один раз. Прерванный запрос может быть повторён с тем же идентификатором запроса Model Gate, даже если поставщик уже принял его. Защита от повторного списания не обеспечивает однократность внешних действий инструментов. Делайте инструменты приложения и внешние побочные эффекты идемпотентными.

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

Тарифы и учёт

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

При коэффициенте 0.5 за элемент с обычной стоимостью Model Gate 0.02 списывается 0.01. Официальная справочная цена не меняется. Применённый коэффициент фиксируется и сохраняется в запросе для аудита.

Ошибки

{
  "error": {
    "message": "line 2 url must match batch endpoint /v1/responses",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_batch_file"
  }
}

Images не является элементом Batch

/v1/images/generations и /v1/images/edits не поддерживаются как пакетные эндпоинты. Используйте специализированный API операций с изображениями, который сохраняет защиту от повторной платной отправки одного намерения. Старый элемент очереди с изображением возвращает images_dedicated_api_required без нового обращения к поставщику; это не доказывает, что предыдущая попытка была бесплатной. Не возвращайте такие элементы в очередь массово.

Распознавание речи доступно только через специализированный API транскрибации, а не через эту очередь. Аудиопуть, запущенный через общую очередь, отклоняется с audio_dedicated_api_required; не ставьте его повторно в очередь как новый платный запрос.

Специализированные операции Video не принимаются этой общей очередью. Используйте JSON API Video с собственным Idempotency-Key и историей операций; попытка отправки Video через старый путь завершается с video_dedicated_api_required до обращения к поставщику. API Video.