Batch API kompatibilné s OpenAI

Model Gate implementuje pracovný postup OpenAI Files + Batch https://api.model-gate.com/v1. Toto je vrstva kompatibility: každá položka JSONL sa vykonáva cez normálnu cestu odvodenia modelu Gate. Model Gate áno nie odošlite dávku OpenAI natívneho poskytovateľa.

Súbory/dávkové čítanie/kontrola koncových bodov sú kontrolnou rovinou: inak platné aktívne poverenie API môže vypisovať/čítať/sťahovať/zrušiť/odstrániť existujúce zdroje, aj keď je zostatok na účte momentálne nulový alebo je vyčerpaný resetovateľný limit výdavkov. Operácie výroby skladu sú rôzne: POST /v1/files a POST /v1/batches vyžadovať nový kladný zostatok/prijatie výdavkov predtým, ako Model Gate vloží údaje o súbore/úlohe/položke. Kľúč s nulovým zostatkom preto nemôže nahrať JSONL ani vytvoriť nové dávkové úložisko. Skutočné položky šarže stále znova kontrolujú príjem v čase nároku pracovníka a zostávajú v rade, ak sa prostriedky neskôr vyčerpajú. Vstup JSONL sa číta postupne a overuje/vkladá sa riadok po riadku; Model Gate si počas vytvárania dávky neuchová celý vstup 200 MB plus všetky telá požiadaviek v pamäti procesu. Kvóty uloženého bajtu/súboru/aktívnej úlohy/položky na používateľa poskytujú nezávislú hranicu zneužitia databázy.

Podporované koncové body dávky v tomto vydaní sú:

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

Každá vykonaná položka je označená request_mode=batch, batch_protocol=openai, s jeho batch_job_public_id a custom_id.

1. Nahrajte vstupný súbor JSONL

Každý neprázdny riadok obsahuje custom_id, method, urla body. Adresa URL sa musí zhodovať s koncovým bodom dodaným neskôr /v1/batches.

Príklad 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."}}

Žiadosť

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

Odpoveď - 200

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

2. Vytvorte dávku

completion_window musí byť 24h.

Žiadosť

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

Odpoveď - 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. Získajte dávku

Žiadosť

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

Odpoveď - dokončená

{
  "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. Stiahnite si výsledky

Žiadosť

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

Odpoveď - 200

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

Položky, ktoré zlyhali, boli zrušené alebo ktorých platnosť vypršala, sa zapíšu do error_file_id ako JSONL záznamy s response:null a error objekt.

5. Vypíšte šarže

limit predvolene na 20 a musí byť z 1 do 100. Použite after pre stránkovanie kurzora.

Žiadosť

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

Odpoveď - 200

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

Dokončené dávkové objekty môžu obsahovať agregát usage je k dispozícii účtovanie požiadaviek Model Gate.

6. Zrušte dávku

Zrušiť zabráni spusteniu položiek vo fronte; už spracovávaná položka sa môže dokončiť.

Žiadosť

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

Odpoveď - 200

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

7. Metadáta súboru, zoznam a vymazanie

Získať metadáta:

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
}

Zoznam súborov s voliteľným purpose, aftera order=asc|desc; limit predvolene na 10000 a musí byť z 1 do 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
}

Odstrániť nereferencovaný/kompatibilný súbor s vypršanou platnosťou:

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

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

Limity a sémantika obnovy

Model Gate akceptuje až 50 000 položiek JSONL a obmedzuje nahrávaný súbor na nakonfigurovaný OPENAI_BATCH_MAX_FILE_BYTES hodnotu (predvolene 200 MiB). Každá jednotlivá položka šarže musí tiež zodpovedať norme Model Gate MAX_REQUEST_BODY_BYTES limit. custom_id hodnoty musia byť jedinečné. Dávkové položky nemožno použiť stream:true alebo vnorené async:true. Veľké súbory JSONL sa uchovávajú interne ako časti databázy, a nie ako jedna nadmerná hodnota SQL.

Obnova vykonania je aspoň raz, nie presne raz. Ak sa pracovník zastaví po prijatí upstream požiadavky, ale predtým, ako sa jej výsledok natrvalo zaznamená, prenájom, ktorého platnosť vypršala, môže spôsobiť opakovanie rovnakého ID požiadavky Model Gate. Vyrovnanie zostáva idempotentné pre už hotové riadky žiadostí, ale nástroj/externé vedľajšie účinky iniciované modelom by mali byť samé osebe idempotentné.

Každá položka JSONL je prijatá bezprostredne predtým, ako si ju pracovník uplatní. V opačnom prípade platné položky zostanú v rade, kým aktuálny zostatok na účte nie je kladný alebo kým je už vyčerpaný limit na výdavky, ktorý možno obnoviť kľúčom/skupinou. Tento stav čakania nespotrebuje pokus ani nevytvorí záznam o chybe; neskoršie dobitie, vynulovanie spotreby alebo zvýšenie limitu automaticky spôsobia, že zostávajúce položky budú vhodné. Model Gate si nerezervuje teoretické maximálne náklady na šaržu. Položky, ktoré už boli prijaté, sa preto môžu v plnej výške vyrovnať, aj keď súbežná práca spôsobí záporný konečný zostatok alebo spôsobí malé prekročenie limitu výdavkov, po ktorom zostanú nové položky v rade, kým účet nebude opäť spôsobilý.

Cenotvorba a účtovníctvo

Dávkový adaptér nepoužíva dávkové spustenie natívneho poskytovateľa. Každá položka prejde normálnym modelom modelovej brány a vysporiadaním, potom dostane cenovú šablónu Koeficient ceny šarže požiadavky. Predvolená hodnota: 1.

Ak je koeficient 0.5, položka, ktorej bežná cena Model Gate je 0.02 sa účtuje ako 0.01. Oficiálna referenčná cena zostáva nezmenená. Použitý koeficient je zaznamenaný a uložený v žiadosti o audit.

Chyby

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