Inferência em lote

A Batch API para Large Language Models permite o processamento assíncrono de inúmeras solicitações de inferência e é totalmente compatível com o padrão da OpenAI API. A Batch API é uma solução econômica quando resultados de inferência imediatos não são necessários. Ela oferece limites de taxa mais altos do que chamadas online, garantindo que os resultados sejam entregues dentro de um prazo razoável de 24 horas. Esta API é ideal para:

Realizar avaliações e análise de dados.
Classificar conjuntos de dados extensos.
Gerar resumos de documentos em modo offline.

Modelos compatíveis:

Início rápido

1. Preparar arquivos de lote

A Batch API usa arquivos no formato .jsonl como entrada, com cada linha representando os detalhes de uma solicitação de inferência da API. Os endpoints disponíveis incluem /v1/chat/completions e /v1/completions.

Defina o parâmetro endpoint como /v1/chat/completions ou /v1/completions para compatibilidade com a OpenAI API.

Cada solicitação deve incluir um custom_id exclusivo para localizar os resultados de inferência no arquivo de saída após a conclusão do lote. Os parâmetros no campo body de cada linha são enviados como parâmetros reais da solicitação de inferência para o endpoint.

Todas as solicitações em um único arquivo JSONL de lote devem direcionar para o mesmo modelo. Não misture solicitações para modelos diferentes em um lote.

Abaixo está um exemplo de arquivo de entrada contendo 2 solicitações:

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. Fazer upload do arquivo de entrada do lote

Faça upload do arquivo de entrada do lote para garantir que ele possa ser referenciado com precisão ao criar um lote. Use a Files API para fazer upload do seu arquivo .jsonl e defina o purpose como batch. Observe que o arquivo será retido por 15 dias.

Para saber como obter a chave de API, consulte Gerenciamento de chaves de API.

Exemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

Resposta de exemplo após o upload bem-sucedido do arquivo:

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. Criar um lote

Depois que o arquivo de entrada for carregado com sucesso, você poderá iniciar um lote usando o ID do objeto File carregado. A janela de conclusão é fixa em 24h e atualmente não é ajustável. Exemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

Esta solicitação retornará um objeto Batch que inclui metadados sobre seu lote, conforme ilustrado no exemplo abaixo:

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. Verificar o status de um lote

Você pode verificar o status de um lote a qualquer momento para receber as informações mais recentes do lote. Os valores de enumeração de status do objeto Batch são os seguintes:

Status	Descrição
VALIDATING	O arquivo de entrada está sendo validado antes que o lote possa começar
PROGRESS	O lote está em andamento
COMPLETED	O processamento do lote foi concluído com sucesso
FAILED	O processamento do lote falhou
EXPIRED	O lote excedeu o prazo
CANCELLING	O lote está sendo cancelado
CANCELLED	O lote foi cancelado

Exemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. Recuperar os resultados

Depois que a inferência em lote for concluída, você poderá baixar o arquivo de saída de resultados usando o campo output_file_id do objeto Batch. O arquivo de saída de resultados será excluído 30 dias após a conclusão da inferência em lote, portanto, recupere-o prontamente por meio da interface. Exemplo de código Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

A resposta retorna o conteúdo bruto do arquivo. Para arquivos de saída em lote, cada linha contém uma resposta como esta:

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

Instruções

Limitações

Cada lote pode conter até 50.000 solicitações.
O tamanho máximo do arquivo de entrada por lote é de 100 MB.

Tratamento de erros

Erros encontrados durante o processamento em lote são registrados em um arquivo de erro separado, acessível por meio do campo error_file_id. Códigos de erro comuns incluem:

Código de erro	Descrição	Solução
400	Formato de solicitação inválido	Verifique a sintaxe JSONL e os campos obrigatórios
401	Falha na autenticação	Verifique a chave de API
404	Lote não encontrado	Verifique o ID do lote
429	Limite de taxa excedido	Reduza a frequência das solicitações
500	Erro do servidor	Entre em contato conosco

Expiração de lotes

Lotes não concluídos em 24 horas passarão para o estado EXPIRED. Solicitações não finalizadas serão canceladas, enquanto solicitações concluídas serão fornecidas por meio de um arquivo de saída. Você paga apenas pelos tokens consumidos pelas solicitações concluídas. O lote faz todos os esforços para ser concluído em 24 horas.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Início rápido

1. Preparar arquivos de lote

2. Fazer upload do arquivo de entrada do lote

3. Criar um lote

4. Verificar o status de um lote

5. Recuperar os resultados

Instruções

Limitações

Tratamento de erros

Expiração de lotes

Todas as APIs de lote

​Início rápido

​1. Preparar arquivos de lote

​2. Fazer upload do arquivo de entrada do lote

​3. Criar um lote

​4. Verificar o status de um lote

​5. Recuperar os resultados

​Instruções

​Limitações

​Tratamento de erros

​Expiração de lotes

​Todas as APIs de lote

Início rápido

1. Preparar arquivos de lote

2. Fazer upload do arquivo de entrada do lote

3. Criar um lote

4. Verificar o status de um lote

5. Recuperar os resultados

Instruções

Limitações

Tratamento de erros

Expiração de lotes

Todas as APIs de lote