OpenAI-kompatible Batch-API

Model Gate implementiert den OpenAI Files + Batch-Workflow https://api.model-gate.com/v1. Dies ist eine Kompatibilitätsschicht: Jedes JSONL-Element wird über den normalen Model Gate-Inferenzpfad ausgeführt. Model Gate tut es nicht Senden Sie einen Upstream-Provider-nativen OpenAI-Batch.

Dateien/Batch-Lese-/Steuerungsendpunkte sind eine Steuerungsebene: Ein ansonsten gültiger aktiver API-Zugang kann vorhandene Ressourcen auflisten/lesen/herunterladen/abbrechen/löschen, selbst wenn der Kontostand derzeit Null ist oder ein rücksetzbares Ausgabenlimit ausgeschöpft ist. Speichererzeugende Vorgänge sind unterschiedlich: POST /v1/files Und POST /v1/batches Es ist ein neuer positiver Saldo/Ausgabenzugang erforderlich, bevor Model Gate Datei-/Auftrags-/Artikeldaten einfügt. Ein Null-Saldo-Schlüssel kann daher weder JSONL hochladen noch einen neuen Batch-Speicher erstellen. Tatsächliche Batch-Artikel prüfen die Zulassung zum Zeitpunkt des Arbeitnehmeranspruchs noch einmal und bleiben in der Warteschlange, wenn die Mittel später erschöpft sind. Die JSONL-Eingabe wird inkrementell gelesen und Zeile für Zeile validiert/eingefügt. Model Gate behält beim Erstellen eines Batches nicht die gesamten 200 MB Eingabe plus alle Anforderungstexte im Prozessspeicher bei. Kontingente pro Benutzer für gespeicherte Bytes/Dateien/aktive Jobs/Warteschlangenelemente bieten eine unabhängige Grenze für Datenbankmissbrauch.

Unterstützte Batch-Endpunkte in dieser Version sind:

• /v1/responses
• /v1/chat/completions
• /v1/embeddings
• /v1/images/generations

Jeder ausgeführte Artikel wird markiert request_mode=batch, batch_protocol=openai, mit seinem batch_job_public_id Und custom_id.

1. Laden Sie eine JSONL-Eingabedatei hoch

Jede nicht leere Zeile enthält custom_id, method, url, Und body. Die URL muss mit dem später bereitgestellten Endpunkt übereinstimmen /v1/batches.

Beispiel 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."}}

Anfrage

curl https://api.model-gate.com/v1/files \
  -H "Authorization: Bearer mg_live_..." \
  -F "purpose=batch" \
  -F "[email protected]"

Antwort – 200

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

2. Erstellen Sie den Stapel

completion_window muss sein 24h.

Anfrage

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"}
  }'

Antwort – 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. Rufen Sie einen Stapel ab

Anfrage

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

Antwort – abgeschlossen

{
  "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. Ergebnisse herunterladen

Anfrage

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

Antwort – 200

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

Auf fehlgeschlagene, abgebrochene oder abgelaufene Elemente wird geschrieben error_file_id als JSONL-Aufzeichnungen mit response:null und ein error Objekt.

5. Chargen auflisten

limit Standardmäßig ist 20 und muss von sein 1 Zu 100. Verwenden after für Cursor-Paginierung.

Anfrage

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

Antwort – 200

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

Abgeschlossene Batch-Objekte können ein Aggregat enthalten usage Objekt bei Abrechnung ist Model Gate-Anforderungsabrechnung verfügbar.

6. Brechen Sie einen Stapel ab

Abbrechen verhindert, dass in der Warteschlange befindliche Elemente gestartet werden. Ein Artikel, der bereits verarbeitet wird, kann beendet werden.

Anfrage

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

Antwort – 200

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

7. Dateimetadaten, Auflistung und Löschung

Metadaten abrufen:

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
}

Dateien mit optional auflisten purpose, after, Und order=asc|desc; limit Standardmäßig ist 10000 und muss von sein 1 Zu 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
}

Löschen Sie eine nicht referenzierte/abgelaufene kompatible Datei:

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

{
  "id": "file-01K...",
  "object": "file",
  "deleted": true
}

Grenzen und Wiederherstellungssemantik

Model Gate akzeptiert bis zu 50.000 JSONL-Elemente und beschränkt die hochgeladene Datei auf die konfigurierten OPENAI_BATCH_MAX_FILE_BYTES Wert (standardmäßig 200 MiB). Jeder einzelne Chargenartikel muss auch zur Norm von Model Gate passen MAX_REQUEST_BODY_BYTES Limit. custom_id Werte müssen eindeutig sein. Batch-Elemente können nicht verwendet werden stream:true oder verschachtelt async:true. Große JSONL-Dateien werden intern als Datenbankblöcke und nicht als ein übergroßer SQL-Wert gespeichert.

Die Wiederherstellung der Ausführung erfolgt mindestens einmal, nicht genau einmal. Wenn ein Worker stoppt, nachdem eine Upstream-Anfrage angenommen wurde, aber bevor das Ergebnis dauerhaft aufgezeichnet wird, kann eine abgelaufene Lease dazu führen, dass dieselbe Model Gate-Anfrage-ID erneut versucht wird. Die Abwicklung bleibt für bereits abgeschlossene Anforderungszeilen idempotent, aber von einem Modell initiierte Tool-/externe Nebenwirkungen sollten selbst idempotent sein.

Jedes JSONL-Element wird sofort zugelassen, bevor ein Arbeiter es beansprucht. Ansonsten gültige Artikel bleiben in der Warteschlange, solange der aktuelle Kontostand nicht positiv ist oder das rücksetzbare Ausgabenlimit für Schlüssel/Gruppen bereits ausgeschöpft ist. Dieser Wartezustand verbraucht keinen Versuch und erstellt keinen Fehlerdatensatz. Bei einer späteren Aufladung, einer Zurücksetzung der Nutzung oder einer Erhöhung des Limits sind die verbleibenden Artikel automatisch berechtigt. Model Gate reserviert keine theoretischen maximalen Chargenkosten. Bereits zugelassene Artikel können daher vollständig abgerechnet werden, auch wenn gleichzeitige Arbeiten den Endsaldo negativ machen oder zu einer geringfügigen Überschreitung des Ausgabenlimits führen. Danach bleiben neue Artikel in der Warteschlange, bis das Konto wieder berechtigt ist.

Preisgestaltung und Buchhaltung

Der Batch-Adapter verwendet keine anbieternative Batch-Ausführung. Jeder Artikel durchläuft das normale Model Gate-Modellrouting und die Abrechnung und erhält dann die Preisvorlagen Preiskoeffizient für Chargenanfrage. Standard: 1.

Wenn der Koeffizient ist 0.5, ein Gegenstand, dessen normale Modelltorkosten betragen 0.02 wird abgebucht als 0.01. Der offizielle Referenzpreis bleibt unverändert. Der angewandte Koeffizient wird in der Anfrage zur Prüfung erfasst und gespeichert.

Fehler

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