Texto
Create Message
Cria uma mensagem usando o formato da Anthropic Messages API
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
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.
Versão da API da Anthropic. Os SDKs da Anthropic enviam isso para você; use 2023-06-01 ao chamar a API diretamente.
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.
ID de um modelo que suporta o formato anthropic_messages. Verifique os detalhes do modelo para capacidades atuais.
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..." } }
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.
Prompt de sistema como uma string ou um array de blocos de conteúdo de texto, separado do array messages.
Temperatura de amostragem. O suporte, valores permitidos e o padrão dependem do modelo selecionado; omita este campo para usar o padrão.
falseRetorna a resposta como um fluxo de eventos enviados pelo servidor (SSE). Veja Streaming.
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.
Ferramentas disponíveis para o modelo. O suporte depende do modelo selecionado.
Objeto de escolha de ferramenta nativo, por exemplo {"type":"auto"}. Os tipos suportados dependem do modelo selecionado.
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.
Parâmetro de amostragem Nucleus. Use temperatura ou top_p, não ambos. O suporte depende do modelo selecionado.
Amostra apenas das K opções principais para cada token. O suporte depende do modelo selecionado.
Sequências de parada personalizadas que farão o modelo parar de gerar. Até 8.191 entradas.
Metadados da requisição no formato Anthropic. user_id é um identificador opaco para seu usuário final.
Apenas auto e standard_only têm efeito. O TokenLab precifica apenas o nível standard e ignora qualquer outro valor.
Resposta
Identificador único da mensagem.
Sempre message.
Sempre assistant.
Array de blocos de conteúdo, como text, thinking ou tool_use.
Modelo que produziu a resposta.
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.
A sequência de parada que encerrou a geração, ou null.
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
{
"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
200quando ocorre uma falha. Uma falha após o início do fluxo chega como um eventoevent: errorcom 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"
}| Status | error.type | Causa típica |
|---|---|---|
| 400 | invalid_request_error | Um campo ausente ou inválido, um modelo desconhecido ou um modelo que não aceita o formato Messages |
| 401 | authentication_error | A chave de API está ausente ou inválida |
| 402 | billing_error | O 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 |
| 403 | permission_error | A chave de API não pode usar o modelo solicitado, ou a conta está suspensa ou restrita |
| 409 | conflict_error | Uma nova tentativa com o mesmo Idempotency-Key. Veja Tente novamente com segurança usando uma chave de idempotência |
| 413 | request_too_large | A entrada da requisição é muito grande |
| 429 | rate_limit_error | Muitas requisições |
| 500, 502, 503 | api_error ou overloaded_error | A requisição não pôde ser concluída, ou nenhuma rota está disponível para ela agora. Tente novamente mais tarde |
| 504 | timeout_error | A requisição excedeu o tempo limite |
Interfaces relacionadas
- Contar tokens de mensagem: estime os tokens de entrada de uma requisição antes de enviá-la.
- Message Batches executam muitas requisições de Messages de forma assíncrona: criar, listar, recuperar, cancelar, obter resultados e excluir.
Autorização
BearerAuth Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Cabeçalhos
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"
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.
1 <= length <= 255Corpo 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