B2BB2B LLM

API de lote compatível com OpenAI

Carregue arquivos de entrada em lote JSONL e processe lotes compatíveis com OpenAI por meio da fila durável do Model Gate.

API de lote compatível com OpenAI

Model Gate implementa o fluxo de trabalho OpenAI Files + Batch em https://api.model-gate.com/v1. Esta é uma camada de compatibilidade: cada item JSONL é executado através do caminho de inferência normal do Model Gate. Modelo Gate faz não enviar um lote OpenAI nativo do provedor upstream.

Os endpoints de leitura/controle de arquivos/lote são um plano de controle: uma credencial de API ativa válida pode listar/ler/baixar/cancelar/excluir recursos existentes mesmo quando o saldo da conta é atualmente zero ou um limite de gastos redefinível está esgotado. As operações de produção de armazenamento são diferentes: POST /v1/files e POST /v1/batches exigir nova admissão de saldo positivo/gastos antes que o Model Gate insira dados de arquivo/trabalho/item. Portanto, uma chave de saldo zero não pode fazer upload de JSONL ou criar novo armazenamento em lote. Os itens reais do lote ainda verificam novamente a admissão no momento da reivindicação do trabalhador e permanecem na fila se os fundos se esgotarem posteriormente. A entrada JSONL é lida de forma incremental e validada/inserida linha por linha; O Model Gate não retém a entrada completa de 200 MB mais todos os corpos da solicitação na memória do processo ao criar um lote. As cotas de bytes armazenados/arquivos/trabalho ativo/item na fila por usuário fornecem um limite independente de abuso de banco de dados.

Os endpoints em lote suportados nesta versão são:

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

Cada item executado é marcado request_mode=batch, batch_protocol=openai, com seu batch_job_public_id e custom_id.

1. Faça upload de um arquivo de entrada JSONL

Cada linha não vazia contém custom_id, method, url, e body. O URL deve ser igual ao endpoint fornecido posteriormente para /v1/batches.

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

Solicitar

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

Resposta – 200

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

2. Crie o lote

completion_window deve ser 24h.

Solicitar

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

Resposta – 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. Recuperar um lote

Solicitar

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

Resposta - concluída

{
  "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. Baixe os resultados

Solicitar

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

Resposta – 200

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

Itens com falha, cancelados ou expirados são gravados em error_file_id como registros JSONL com response:null e um error objeto.

5. Listar lotes

limit o padrão é 20 e deve ser de 1 para 100. Usar after para paginação do cursor.

Solicitar

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

Resposta – 200

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

Objetos de lote concluídos podem incluir um agregado usage objeto quando a contabilidade de solicitação do Model Gate liquidada estiver disponível.

6. Cancelar um lote

Cancelar impede que itens na fila sejam iniciados; um item já processado pode terminar.

Solicitar

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

Resposta – 200

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

7. Metadados, listagem e exclusão de arquivos

Recuperar metadados:

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
}

Listar arquivos com opcional purpose, after, e order=asc|desc; limit o padrão é 10000 e deve ser de 1 para 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
}

Exclua um arquivo compatível não referenciado/expirado:

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

Limites e semântica de recuperação

O Model Gate aceita até 50.000 itens JSONL e limita o arquivo carregado ao configurado OPENAI_BATCH_MAX_FILE_BYTES valor (200 MiB por padrão). Cada item de lote individual também deve caber no padrão normal do Model Gate MAX_REQUEST_BODY_BYTES limite. custom_id os valores devem ser exclusivos. Itens de lote não podem ser usados stream:true ou aninhado async:true. Arquivos JSONL grandes são persistidos internamente como partes do banco de dados, em vez de um valor SQL superdimensionado.

A recuperação da execução é pelo menos uma vez, não exatamente uma vez. Se um trabalhador parar depois que uma solicitação upstream for aceita, mas antes que seu resultado seja registrado de forma durável, um arrendamento expirado poderá fazer com que o mesmo ID de solicitação do Model Gate seja repetido. A liquidação permanece idempotente para linhas de solicitação já concluídas, mas os efeitos colaterais externos/ferramentas iniciados por um modelo devem ser idempotentes.

Cada item JSONL é admitido imediatamente antes de um trabalhador reivindicá-lo. Os itens válidos permanecem na fila enquanto o saldo da conta atual não é positivo ou o limite de gastos redefinível da chave/grupo já está esgotado. Este estado de espera não consome uma tentativa nem cria um registro de erro; uma recarga posterior, uma redefinição de uso ou um aumento de limite tornam automaticamente os itens restantes elegíveis. A Model Gate não reserva um custo máximo teórico do lote. Os itens já admitidos podem, portanto, ser liquidados integralmente mesmo quando o trabalho simultâneo torna o saldo final negativo ou produz uma pequena ultrapassagem do limite de gastos, após o que novos itens permanecem na fila até que a conta seja elegível novamente.

Preços e contabilidade

O adaptador em lote não usa execução em lote nativa do provedor. Cada item passa pelo roteamento e liquidação normal do modelo Model Gate e, em seguida, recebe o modelo de precificação Coeficiente de preço de solicitação em lote. Padrão: 1.

Se o coeficiente for 0.5, um item cujo custo normal do Model Gate é 0.02 é debitado como 0.01. O preço de referência oficial permanece inalterado. O coeficiente aplicado é capturado e armazenado na solicitação de auditoria.

Erros

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