Texto

Criar Chat Completion

Cria uma conclusão para a mensagem de chat

POST
/v1/chat/completions

Corpo da Requisição

Parâmetros opcionais suportados, valores aceitos e padrões dependem do modelo selecionado. Verifique os detalhes do modelo antes de definir opções de amostragem, raciocínio ou ferramentas. Um controle que o modelo não consegue honrar, como n acima de 1 em alguns modelos, é rejeitado com um erro 4xx. Controles de amostragem menores, como seed ou as penalidades, podem ser ignorados.

modelstringobrigatório

ID do modelo a ser utilizado. Veja Modelos para opções disponíveis.

messagesarrayobrigatório

Uma lista de mensagens que compõem a conversa.

Cada objeto de mensagem contém:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): O conteúdo da mensagem

Para uma mensagem do assistant contendo tool_calls, o content pode ser omitido ou definido como null.

Quando content é um array, o TokenLab suporta blocos multimodais estruturados para modelos compatíveis:

  • texto: { "type": "text", "text": "..." }
  • imagem: { "type": "image_url", "image_url": { "url": "https://..." } }
  • vídeo: { "type": "video_url", "video_url": { "url": "https://..." } }
  • áudio: { "type": "input_audio", "input_audio": { "data": "https://... ou URL de dados base64", "format": "wav" } }, ou { "type": "audio_url", "audio_url": { "url": "https://..." } }

Para entrada multimodal, use URLs https publicamente acessíveis. Imagens também podem ser enviadas como URLs de dados base64. Os tipos de mídia suportados dependem do modelo selecionado.

temperaturenumber

Temperatura de amostragem. O suporte, os valores permitidos e o padrão dependem do modelo selecionado; omita este campo para usar o padrão.

max_tokensinteger

Número máximo de tokens a serem gerados. Envie max_tokens ou max_completion_tokens, não ambos: um modelo servido por outro protocolo pode rejeitar uma requisição que contenha ambos.

Em um modelo que pensa, os tokens de raciocínio contam para este limite. Se o limite for muito pequeno, todo o orçamento pode ser consumido pelo raciocínio, deixando um corpo de mensagem vazio, e os tokens usados ainda serão cobrados. Aumente o limite ou desative o raciocínio onde o modelo permitir, por exemplo, com "reasoning_effort": "none". No deepseek-v4.1-flash (apelido deepseek-flash), "thinking": {"type": "disabled"} também o desativa.

Antes da execução da requisição, o TokenLab verifica se o seu saldo cobre este máximo. Um valor muito grande pode retornar 402 com saldo baixo, mesmo quando a resposta for curta.

streambooleanpadrão: false

Se verdadeiro, deltas de mensagens parciais são enviados como eventos enviados pelo servidor (SSE). Veja Streaming.

Para saídas longas (milhares de tokens ou mais), defina stream: true para que clientes e proxies não excedam o tempo limite enquanto aguardam a resposta completa.

stream_optionsobject

Opções para streaming. Defina include_usage: true para receber um chunk extra com o uso de tokens antes de data: [DONE]. Sem isso, o stream não carrega informações de uso.

top_pnumber

Parâmetro de amostragem Nucleus. Recomendamos alterar este ou a temperatura, não ambos.

frequency_penaltynumber

Número entre -2.0 e 2.0. Valores positivos penalizam tokens repetidos.

presence_penaltynumber

Número entre -2.0 e 2.0. Valores positivos penalizam tokens que já estão no texto.

stopstring | array

Sequência de parada ou lista de sequências. O suporte e os limites de sequência dependem do modelo selecionado.

toolsarray

Uma lista de ferramentas que o modelo pode chamar (function calling). Cada ferramenta é { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. Veja Saídas estruturadas e chamada de ferramentas.

tool_choicestring | object

Controla como o modelo usa as ferramentas. Opções: auto, none, required, ou { "type": "function", "function": { "name": "..." } } para forçar uma ferramenta.

parallel_tool_callsboolean

Permite múltiplas chamadas de ferramentas em um turno do assistente, quando suportado pelo modelo selecionado.

max_completion_tokensinteger

Limite superior para a conclusão, incluindo tokens de raciocínio. Alternativa ao max_tokens usada por famílias de modelos OpenAI mais recentes. Envie apenas um dos dois.

reasoning_effortstring

Esforço de raciocínio para modelos que o suportam. Os valores aceitos dependem do modelo selecionado.

Para modelos Claude, o valor define o raciocínio do modelo: um nível de esforço em modelos com raciocínio adaptativo, ou um orçamento de raciocínio em modelos que utilizam um. none desativa o raciocínio em modelos que permitem isso. Um valor que o modelo não suporta é rejeitado com 400, código invalid_value, e o erro lista os valores suportados. Enquanto o raciocínio está ativado, o Claude rejeita uma temperature diferente de 1, top_k, um top_p fora de 0.95–1 e uma mensagem de assistente pré-preenchida. Um tool_choice forçado funciona com raciocínio adaptativo, mas não com um orçamento de raciocínio.

anthropic_optionsobject

Opções para modelos Claude.

  • prompt_caching (boolean): Defina true para fazer cache do início do prompt. O TokenLab marca o fim do prompt do sistema e a última mensagem do usuário como pontos de cache. Uma requisição posterior que comece com o mesmo conteúdo o lerá do cache. Use esta opção ou suas próprias marcas de cache_control, não ambas.
  • prompt_caching_ttl (string): 5m (padrão) ou 1h. Quando o serviço que processa a requisição não consegue manter um cache por uma hora, o TokenLab pode usar o cache de cinco minutos em vez de rejeitar a requisição.

extra.prompt_caching e extra.prompt_caching_ttl são aceitos como as mesmas opções. Veja Prompt caching para preços e como verificar os tokens em cache.

seedinteger

Semente de amostragem para modelos que a suportam. Saída idêntica não é garantida.

ninteger

Número de conclusões a serem geradas. Modelos que suportam aceitam de 1 a 128. Muitos modelos suportam apenas 1.

logprobsboolean

Se deve retornar probabilidades de log.

top_logprobsinteger

Número de probabilidades de log principais a serem retornadas (0-20). Requer logprobs: true.

top_kinteger

Amostragem Top-K para modelos que a suportam.

response_formatobject

Formato de resposta. Use {"type": "text"} (padrão), {"type": "json_object"} para modo JSON, ou {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} para um esquema JSON. O suporte depende do modelo selecionado. Veja Saídas estruturadas e chamada de ferramentas.

logit_biasobject

Modifica a probabilidade de tokens especificados aparecerem. Mapeie IDs de token (como strings) para valores de viés de -100 a 100. O suporte depende do modelo selecionado.

service_tierstring

O TokenLab serve e cobra requisições de Chat no nível de serviço padrão. auto e default são aceitos. Outros valores, como flex ou priority, são removidos da requisição, e a requisição é cobrada pelo preço padrão.

userstring

Um identificador único representando seu usuário final para monitoramento de abuso.

Resposta

idstring

Identificador único para a conclusão.

objectstring

Sempre chat.completion.

createdinteger

Timestamp Unix de quando a conclusão foi criada.

modelstring

O modelo usado para a conclusão.

choicesarray

Lista de escolhas de conclusão.

Cada escolha contém:

  • index (integer): Índice da escolha
  • message (object): A mensagem gerada
  • finish_reason (string): Por que o modelo parou, por exemplo stop, length, tool_calls ou content_filter

Quando o modelo pensa, a message também pode conter:

  • reasoning_content (string): O texto de raciocínio. Alguns modelos retornam apenas um resumo ou nenhum texto.
  • reasoning_details (array): Blocos de raciocínio com suas assinaturas. Para continuar uma conversa com raciocínio, por exemplo após uma chamada de ferramenta, envie-os de volta inalterados na mensagem do assistente.

Em um stream, os mesmos campos chegam como delta.reasoning_content e delta.reasoning_details.

usageobject

Estatísticas de uso de tokens.

  • prompt_tokens (integer): Tokens no prompt
  • completion_tokens (integer): Tokens na conclusão, incluindo tokens de raciocínio
  • total_tokens (integer): Total de tokens usados
  • prompt_tokens_details.cached_tokens (integer): Tokens de prompt lidos do cache
  • cache_creation_input_tokens (integer): Tokens de prompt gravados no cache. Presente apenas quando o valor é maior que 0
  • completion_tokens_details.reasoning_tokens (integer): Tokens de raciocínio, quando o modelo os reporta

Em um stream, o uso chega apenas quando stream_options.include_usage é true.

Requisição

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Exemplo Multimodal

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Resposta

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

Com stream: true, a resposta é um text/event-stream. Cada evento é data: {...} com um objeto chat.completion.chunk cujo choices[].delta carrega o novo texto, argumentos de chamada de ferramenta ou texto de raciocínio. O stream termina com data: [DONE]. Linhas que começam com : são comentários de keep-alive: ignore-os. Um stream que termina sem [DONE] ou sem um finish_reason está incompleto. Veja Streaming.

Erros

Os erros usam o objeto error no estilo OpenAI. Casos comuns: 400 para um campo inválido ou um valor que o modelo não aceita, 401 para uma chave inválida, 402 para saldo insuficiente, 413 para entrada acima do limite de tamanho e 429 para o limite de taxa. Veja Tratar erros da API.

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Chave opcional que impede uma segunda execução da mesma requisição. Envie um novo valor único, como um UUID, para cada requisição e mantenha-o para novas tentativas após um timeout. Uma nova tentativa com a mesma chave não é executada novamente: ela retorna 409 com idempotency_replay_unavailable, ou geralmente idempotency_conflict quando o corpo foi alterado. Exceção: quando um resultado sem streaming é concluído após o cliente se desconectar, uma nova tentativa com a mesma chave e corpo dentro de 24 horas retorna esse resultado (até 1 MB) com o cabeçalho Idempotent-Replayed: true e sem cobrança adicional. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json