Texto

Create Message

Cria uma mensagem usando o formato da Anthropic Messages API

POST
/v1/messages

Visão Geral

Este endpoint aceita o formato nativo Anthropic Messages, portanto, os SDKs da Anthropic e as ferramentas construídas sobre eles funcionam com a URL base do TokenLab. Ele funciona com modelos cujos accepted_request_formats listam anthropic_messages: modelos Claude e alguns outros modelos.

messages contém turnos de user e assistant. Coloque as instruções de sistema no campo system de nível superior. max_tokens é obrigatório. Para mensagens no estilo OpenAI com papéis como system ou tool, use Chat Completions.

URL base para o SDK da Anthropic: https://api.tokenlab.sh (sem o sufixo /v1)

Cabeçalhos de Requisição

x-api-keystringheader

Sua chave de API do TokenLab. Envie x-api-key ou Authorization: Bearer <API_KEY>. Se você enviar ambos com valores diferentes, o TokenLab utiliza o x-api-key.

anthropic-versionstringheader

Versão da API da Anthropic. Os SDKs da Anthropic enviam isso para você; use 2023-06-01 ao chamar a API diretamente.

anthropic-betastringheader

Nomes de recursos beta da Anthropic, separados por vírgulas. O TokenLab repassa o cabeçalho, e se um recurso beta funciona depende do modelo. Conteúdo que referencia um file_id precisa de files-api-2025-04-14.

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.

modelstringobrigatório

ID de um modelo que suporta o formato anthropic_messages. Verifique os detalhes do modelo para capacidades atuais.

messagesarrayobrigatório

Array de objetos de mensagem com role (user ou assistant) e content. Até 100.000 mensagens.

content pode ser uma string simples ou um array de blocos de conteúdo. Para enviar imagens, use blocos de conteúdo estruturados em vez de colocar URLs de imagem ou strings Base64 diretamente no texto simples. Outros blocos nativos, como tool_use, tool_result, thinking e document, são aceitos para modelos que os suportam.

Exemplos de blocos de conteúdo:

  • bloco de texto: { "type": "text", "text": "Descreva esta imagem" }
  • bloco de imagem via URL: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • bloco de imagem via Base64: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerobrigatório

Máximo de tokens a serem gerados. Obrigatório: O TokenLab não adiciona um padrão. O máximo utilizável depende do modelo; veja max_output_tokens nos detalhes do modelo. Um valor grande aumenta o montante que o TokenLab retém do seu saldo enquanto a requisição é executada, e um saldo que não possa cobrir a retenção retornará 402.

systemstring | array

Prompt de sistema como uma string ou um array de blocos de conteúdo de texto, separado do array messages.

temperaturenumber

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

streambooleanpadrão: false

Retorna a resposta como um fluxo de eventos enviados pelo servidor (SSE). Veja Streaming.

thinkingobject

Configuração de raciocínio nativo, por exemplo {"type":"enabled","budget_tokens":10000}. Modos suportados, orçamentos e combinações com outros parâmetros dependem do modelo selecionado. Para um modelo que é conhecido por rejeitar um orçamento manual, o TokenLab executa {"type":"enabled"} como raciocínio adaptativo e ignora budget_tokens.

toolsarray

Ferramentas disponíveis para o modelo. O suporte depende do modelo selecionado.

tool_choiceobject

Objeto de escolha de ferramenta nativo, por exemplo {"type":"auto"}. Os tipos suportados dependem do modelo selecionado.

cache_controlobject

Marcador de cache de prompt, por exemplo {"type":"ephemeral"}; adicione "ttl": "1h" para um cache de uma hora. No nível superior, ele ativa o cache automático. Você também pode defini-lo em blocos system, tools e blocos de conteúdo. O suporte depende do modelo; modelos que o suportam listam prompt-cache em capabilities.

top_pnumber

Parâmetro de amostragem Nucleus. Use temperatura ou top_p, não ambos. O suporte depende do modelo selecionado.

top_kinteger

Amostra apenas das K opções principais para cada token. O suporte depende do modelo selecionado.

stop_sequencesarray

Sequências de parada personalizadas que farão o modelo parar de gerar. Até 8.191 entradas.

metadataobject

Metadados da requisição no formato Anthropic. user_id é um identificador opaco para seu usuário final.

service_tierstring

Apenas auto e standard_only têm efeito. O TokenLab precifica apenas o nível standard e ignora qualquer outro valor.

Resposta

idstring

Identificador único da mensagem.

typestring

Sempre message.

rolestring

Sempre assistant.

contentarray

Array de blocos de conteúdo, como text, thinking ou tool_use.

modelstring

Modelo que produziu a resposta.

stop_reasonstring

Motivo pelo qual a geração parou, como end_turn, max_tokens, stop_sequence ou tool_use. Um modelo pode retornar outros valores, por exemplo refusal.

stop_sequencestring | null

A sequência de parada que encerrou a geração, ou null.

usageobject

Uso de tokens com input_tokens e output_tokens. Quando o modelo reporta tokens de cache de prompt, usage também possui cache_creation_input_tokens e cache_read_input_tokens.

Cada resposta carrega o ID da requisição nos cabeçalhos request-id e X-Request-ID. Cite-o ao entrar em contato com o suporte.

Requisição

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Resposta

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Exemplo de Entrada de Visão

Para modelos Claude com suporte a visão, coloque imagens dentro de messages[].content como blocos de imagem estruturados.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Exemplo de Raciocínio Estendido

Use um modelo com a capacidade reasoning. Ajuste max_tokens e budget_tokens para os limites do modelo; alguns modelos precisam de uma configuração de raciocínio diferente.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Streaming

Defina "stream": true para receber eventos enviados pelo servidor da Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta e message_stop. O uso de tokens chega em message_start e message_delta.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • Enquanto o modelo trabalha, o fluxo pode carregar linhas de comentário SSE como : keep-alive. Os SDKs as ignoram.
  • O status HTTP já pode ser 200 quando ocorre uma falha. Uma falha após o início do fluxo chega como um evento event: error com o mesmo corpo de erro abaixo.

Erros

Os erros usam o formato de erro da Anthropic. request_id é o ID da requisição do TokenLab. Alguns erros adicionam campos como code e hint.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
Statuserror.typeCausa típica
400invalid_request_errorUm campo ausente ou inválido, um modelo desconhecido ou um modelo que não aceita o formato Messages
401authentication_errorA chave de API está ausente ou inválida
402billing_errorO saldo não pode cobrir a requisição (error.code é insufficient_balance). Uma chave de API no seu limite de gastos também recebe 402, com error.code quota_exceeded e error.type rate_limit_error
403permission_errorA chave de API não pode usar o modelo solicitado, ou a conta está suspensa ou restrita
409conflict_errorUma nova tentativa com o mesmo Idempotency-Key. Veja Tente novamente com segurança usando uma chave de idempotência
413request_too_largeA entrada da requisição é muito grande
429rate_limit_errorMuitas requisições
500, 502, 503api_error ou overloaded_errorA requisição não pôde ser concluída, ou nenhuma rota está disponível para ela agora. Tente novamente mais tarde
504timeout_errorA requisição excedeu o tempo limite

Interfaces relacionadas

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

application/json

application/json

application/json

application/json