Solicitação e uso da API Claude Messages

O Anthropic Claude é um sistema de diálogo de IA muito poderoso que, basta inserir um prompt, pode gerar respostas fluentes e naturais em poucos segundos. A API Claude Messages é o formato de API nativo oficial da Anthropic. Diferente do formato compatível com OpenAI (Chat Completion), ela adota a própria estrutura de solicitação e resposta da Anthropic, permitindo utilizar melhor as capacidades exclusivas do Claude, como entrada de conteúdo multimodal, chamada de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados. Este documento apresenta principalmente o processo de uso das operações da API Claude Messages. Com ela, podemos usar uma interface nativa consistente com a oficial da Anthropic para chamar os recursos de diálogo do Claude.

Processo de solicitação

Para usar a API Claude Messages, primeiro acesse o Console do Ace Data Cloud para obter seu API Token e guarde-o para uso posterior.

Se você ainda não tiver feito login ou se registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após concluir, retornará automaticamente para a página atual. Um único API Token permite chamar todos os serviços da plataforma, sem a necessidade de solicitar um separadamente para cada serviço. A primeira solicitação oferece créditos gratuitos para experimentar sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.

📘 Documentação completa: Claude Messages API →

Uso básico

O caminho de solicitação da API Claude Messages é /v1/messages, mantendo-se consistente com a API oficial da Anthropic. Precisamos fornecer pelo menos três parâmetros obrigatórios:

model: escolha o modelo Claude a ser usado. claude-opus-5-5 é fornecido apenas pela API Messages, suporta contexto de 1 milhão de Tokens, saída máxima de 128K Tokens e sempre ativa o pensamento adaptativo. O mais recente modelo principal é o claude-fable-5-1 (contexto de 1 milhão de Tokens, saída máxima de 128K Tokens); o antigo claude-fable-5 permanece mantido por compatibilidade. O claude-sonnet-5-5 foi adicionado à série de interfaces nativas Messages, suportando entrada de imagens e pensamento adaptativo; seus preços de referência oficiais para entrada, saída e leitura de cache são, respectivamente, 2, 10 e 0,20 dólares por milhão de Tokens.
messages: array de mensagens de entrada, em que cada mensagem contém role (função) e content (conteúdo), sendo que role suporta user e assistant.
max_tokens: número máximo de tokens de saída, usado para limitar o comprimento de uma única resposta.

Parâmetros opcionais comuns:

system: prompt de sistema, usado para definir o comportamento e a função do modelo.
temperature: aleatoriedade da geração, entre 0 e 1; quanto maior o valor, mais divergente será a resposta.
stream: se usa resposta em streaming; definido como true, permite o efeito de retorno palavra por palavra.
stop_sequences: sequências de parada personalizadas; o modelo interromperá a geração ao encontrar esses textos.
top_p: parâmetro de amostragem de núcleo, que controla a aleatoriedade da geração junto com temperature.
top_k: amostra somente entre as K opções com maior probabilidade.
tools: definição de ferramentas, usada para permitir que o modelo chame funções externas.
tool_choice: controla como o modelo usa as ferramentas fornecidas.
cache_control: cria automaticamente um ponto de interrupção de cache no último bloco de conteúdo armazenável em cache da solicitação; também pode ser escrito em um bloco de conteúdo específico.

Exemplo cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Exemplo Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Após a chamada, o resultado retornado é o seguinte:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Descrição dos campos do resultado retornado:

id: identificador exclusivo desta mensagem.
type: sempre é message.
role: sempre é assistant.
content: array de conteúdo da resposta; cada elemento contém type (como text) e o conteúdo correspondente.
model: nome do modelo que processou a solicitação.
stop_reason: motivo da interrupção. Os valores estáveis incluem end_turn, max_tokens, stop_sequence, tool_use, pause_turn (você pode reenviar o conteúdo atual do assistant sem alterações para continuar), refusal e model_context_window_exceeded.
stop_sequence: se a interrupção ocorreu devido a uma sequência de parada personalizada, exibe o texto da sequência de parada correspondente.
stop_details: quando stop_reason for refusal, pode incluir a categoria e a descrição da recusa.
usage: estatísticas de uso de tokens. input_tokens é a entrada não armazenada em cache; cache_creation_input_tokens e cache_read_input_tokens são, respectivamente, gravação e leitura de cache; output_tokens é o número total de tokens de saída. Se output_tokens_details.thinking_tokens for retornado, esse valor será um subconjunto de output_tokens; não o some novamente ao calcular o total ou o custo. Esse detalhamento poderá ser null ou ser omitido quando não houver uma contagem confiável.
usage.cache_creation: detalhamento opcional do TTL de gravação de cache, incluindo ephemeral_5m_input_tokens e ephemeral_1h_input_tokens. Quando o objeto existir, a soma dos dois será igual a cache_creation_input_tokens; se o campo for null ou omitido, isso indica que a resposta atual não possui uma divisão de TTL disponível e não deve ser interpretado como 0.
usage.cost: respostas não em streaming podem incluir o objeto de consumo de créditos registrado pelo Ace Data Cloud, em que amount é o consumo real desta vez, currency é a unidade de medição, e list_amount é o valor antes do desconto (se houver). O preço base oficial de leitura de cache do Fable 5.1 é de US $0,25/milhão de Tokens, e os preços base de gravação de cache de 5 minutos e 1 hora são, respectivamente, US$ 12,50 e US$ 20/milhão de Tokens; os preços reais da plataforma são convertidos conforme os descontos do plano.

Prompt de sistema

A API Claude Messages permite definir o prompt de sistema por meio do campo system, usado para definir o comportamento, a função e o contexto do modelo.

Exemplo Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "Você é um assistente profissional de tradução para chinês. Por favor, traduza o inglês inserido pelo usuário para chinês.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Ao definir o prompt system, é possível controlar com precisão o papel e o comportamento do Claude.

Resposta em streaming

Esta interface também oferece suporte a respostas em streaming; basta definir o parâmetro stream como true para obter um efeito de retorno gradual, sendo muito adequado para implementar a exibição palavra por palavra em páginas da web.

Exemplo em Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

A resposta em streaming é retornada no formato Server-Sent Events (SSE), com cada linha prefixada por event: e data:. Os tipos de eventos em streaming incluem:

message_start: início da mensagem, contendo as informações básicas da mensagem e o nome do modelo.
content_block_start: início do bloco de conteúdo.
content_block_delta: atualização incremental do bloco de conteúdo, contendo o fragmento de texto recém-gerado.
content_block_stop: fim do bloco de conteúdo.
message_delta: atualização incremental no nível da mensagem, contendo stop_reason e as informações finais de usage. O valor autoritativo de output_tokens_details.thinking_tokens deve ser lido somente do último message_delta.usage; não o acumule entre eventos.
message_stop: fim da mensagem.

O efeito de saída é o seguinte:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Pode-se ver que, na resposta em streaming, o evento content_block_delta contém o conteúdo de texto gerado gradualmente; ao concatenar todos os text_delta, é possível obter a resposta completa.

Exemplo em JavaScript

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hello, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Conversas com múltiplas rodadas

Se você quiser integrar a funcionalidade de conversas com múltiplas rodadas, deverá alternar as mensagens dos papéis user e assistant no array messages e enviar junto todo o histórico anterior da conversa.

Exemplo em Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O resultado retornado é o seguinte:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Ao transmitir o histórico completo da conversa em messages, o Claude pode fornecer respostas precisas com base no contexto.

Modelo de raciocínio profundo

O thinking e o thinking summary do Claude são dois conceitos diferentes: o modelo pode realizar raciocínio interno, mas a API não retorna a cadeia de pensamento original. Quando é necessário exibir o processo de raciocínio, o que a API retorna é um resumo processado. Atualmente, recomenda-se que o modelo use adaptive thinking e controle o investimento geral de raciocínio por meio de output_config.effort:

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O bloco thinking na resposta tem a seguinte forma:

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" retorna um resumo legível do raciocínio; não é a cadeia de pensamento original.
display: "omitted" retorna thinking: "", mas ainda preserva a signature opaca para oferecer suporte a conversas subsequentes.
display: "updates" é o modo beta da Anthropic, e requer anthropic-beta: thinking-display-updates-2026-08-18. A definição oficial é ocultar o corpo do raciocínio e exibir breves atualizações de progresso entre chamadas de ferramentas. A plataforma transmite esse parâmetro e o cabeçalho beta conforme os valores originais, e não os reescreve forçadamente como summarized; o conteúdo real da saída depende do suporte do modelo selecionado.
thinking, output_config, effort, parâmetros de amostragem e campos de extensão recém-adicionados são transmitidos conforme os valores originais. A plataforma não mantém enumerações de valores codificadas por modelo, restrições de combinação, nem reescreve automaticamente o modo thinking; cabe ao modelo selecionado determinar se aceita esses parâmetros, e os erros de parâmetros retornados pelo modelo serão repassados ao cliente.
Os valores padrão de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 são omitted; Opus 4.6, Sonnet 4.6 e modelos anteriores que suportam thinking usam summarized por padrão.
Display afeta apenas o conteúdo retornado e a latência de streaming, não desativa o raciocínio nem reduz a cobrança de tokens de thinking.
A ativação padrão de thinking e o valor padrão de display são duas questões independentes. Opus 5 e Sonnet 5 ativam adaptive thinking por padrão; para Opus 5, omitir thinking equivale a adaptive, e omitir output_config.effort equivale a high. Opus 4.8, 4.7 e 4.6 exigem ativação explícita.
Thinking e o corpo final compartilham o orçamento de saída de max_tokens. Quando o orçamento é muito pequeno, thinking pode consumir a maior parte do limite, deixando o corpo vazio ou truncado; aumente max_tokens ou use effort low / medium para controlar o investimento de raciocínio.
Para modelos que permitem desativar thinking, é possível passar thinking: {"type":"disabled"}. Novos modos como between_tools e combinações de effort dependem do modelo selecionado; a plataforma não rejeita antecipadamente com base em regras de modelos antigos.
Orçamentos fixos de raciocínio podem ser transmitidos por meio de budget_tokens; novos modelos normalmente usam thinking.type=adaptive e output_config.effort. O suporte a orçamentos fixos ou à desativação de raciocínio depende das capacidades atuais do modelo selecionado.
Em conversas de múltiplos turnos e chamadas de ferramentas, o bloco thinking completo e a signature retornados pelo assistant devem ser enviados de volta sem alterações; não modifique nem gere signatures por conta própria.
A transmissão de parâmetros não significa que todos os modelos suportam todos os recursos. Chamadas entre protocolos ainda exigem conversão, e o escopo de suporte e os erros para conteúdos como redacted_thinking são determinados pelo serviço do modelo que realmente processa a solicitação.

Em solicitações de streaming, summarized produz thinking_delta; omitted não produz thinking_delta, preservando apenas o ciclo de vida do bloco thinking e signature_delta.

Modelos visuais

Claude oferece suporte a entradas multimodais e pode processar texto e imagens simultaneamente. Na Messages API, os recursos visuais podem ser usados definindo content como um formato de array e passando blocos de conteúdo de imagem.

Usando imagens codificadas em Base64

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# 读取并编码图片
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Usando imagens por URL

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Exemplo de cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

Os formatos de imagem suportados incluem: image/jpeg, image/png, image/gif, image/webp.

Documentos e PDF

PDF usa o bloco de conteúdo document, oferecendo suporte a duas fontes estáveis: Base64 e URL. Fontes Base64 devem usar application/pdf:

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

Fontes URL são escritas como {"type":"url","url":"https://example.com/report.pdf"}. document também oferece suporte a text/plain e a fontes content compostas por blocos text/image; os campos opcionais incluem title, context e citations. A fonte file_id da Files API pertence a uma funcionalidade beta independente e não faz parte do contrato estável desta interface.

Cache de prompts

O cache_control de nível superior coloca automaticamente o ponto de interrupção de cache no último bloco armazenável em cache:

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Quando for necessário controlar a posição com precisão, você também pode escrever o mesmo cache_control nos blocos de conteúdo text, image, document, tool_use, tool_result ou nas definições de ferramentas. ttl oferece suporte a 5m (padrão) e 1h; determine a gravação e os acertos do cache por meio de usage.cache_creation_input_tokens e usage.cache_read_input_tokens. Quando a resposta fornecer usage.cache_creation, ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. Se cache_creation for null ou estiver omitido, isso indica que há apenas o total de gravações em cache, sem uma divisão autoritativa de TTL; nesse caso, não trate nenhum bucket como um 0 conhecido, e a cobrança e o total ainda devem se basear no campo agregado. Exemplo de resultado retornado:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Chamada de ferramentas (Tool Use)

A Claude Messages API oferece suporte nativo ao recurso de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções predefinidas quando necessário.

Exemplo em Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Quando o modelo decide chamar uma ferramenta, o content no resultado retornado incluirá um bloco de conteúdo do tipo tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

Observe que stop_reason é tool_use, indicando que o modelo precisa chamar a ferramenta. Após receber esse resultado, você precisa executar a função da ferramenta e retornar o resultado ao modelo na forma de tool_result:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

O modelo gerará a resposta final em linguagem natural com base no resultado retornado pela ferramenta.

Diferenças em relação à Chat Completion API

A Ace Data Cloud fornece simultaneamente dois formatos de Claude API, cujas principais diferenças são as seguintes: O usage.input_tokens da Messages API representa apenas a entrada não armazenada em cache, enquanto cache_read_input_tokens e cache_creation_input_tokens são buckets de cobrança independentes; os três serão calculados separadamente de acordo com os preços correspondentes.

Recurso	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Formato	Formato nativo da Anthropic	Formato compatível com OpenAI
Prompt do sistema	Campo `system` independente	Transmitido por meio de `role: "system"` em `messages`
Estrutura de resposta	Array `content` (oferece suporte a vários tipos)	Array `choices` (inclui `message`)
Formato de streaming	Eventos SSE (vários tipos de evento)	Linhas SSE `data`
Raciocínio profundo	`thinking` nativo e `output_config.effort`	Estratégia padrão do modelo e parâmetros de compatibilidade
Chamada de ferramentas	`tools` + `input_schema` nativos	Formato `tools` compatível com OpenAI
Estatísticas de Token	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

Se o seu sistema já estiver integrado com a API no formato OpenAI, você pode usar a Chat Completion API para alternar perfeitamente. Se precisar usar todos os recursos nativos do Claude, é recomendável usar a Messages API.

Tratamento de erros

As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: error.code é um código de erro estável, error.message é uma descrição, e trace_id é usado para investigar a solicitação. Os status HTTP comuns incluem:

400: os parâmetros da solicitação ou o conteúdo do protocolo são inválidos.
401: o token de autorização é inválido, está ausente ou expirou.
403: acesso proibido, saldo insuficiente ou cota limitada.
404: a API ou o modelo não existe.
413: o corpo da solicitação é grande demais.
429: solicitações demais.
500 / 503 / 504: erro de serviço, indisponibilidade temporária ou tempo limite de processamento excedido.

Exemplo de resposta de erro

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Essa estrutura de erro é o contrato de tempo de execução da Ace Data Cloud e não equivale ao envelope de erro oficial da Anthropic; processe-a de acordo com o status HTTP e error.code.

Conclusão

Através deste documento, você já aprendeu como usar a API Claude Messages para chamar a funcionalidade de conversação do Claude no formato nativo da Anthropic. A API Messages oferece suporte a recursos avançados, como conversas básicas, prompts de sistema, respostas em streaming, conversas de múltiplas rodadas, raciocínio aprofundado, compreensão visual, PDFs, cache de prompts e chamadas de ferramentas. Caso tenha alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Solicitação e uso da API Claude Messages

Processo de solicitação

Uso básico

Exemplo cURL

Exemplo Python

Prompt de sistema

Exemplo Python

Resposta em streaming

Exemplo em Python

Exemplo em JavaScript

Conversas com múltiplas rodadas

Exemplo em Python

Modelo de raciocínio profundo

Modelos visuais

Usando imagens codificadas em Base64

Usando imagens por URL

Exemplo de cURL

Documentos e PDF

Cache de prompts

Chamada de ferramentas (Tool Use)

Exemplo em Python

Diferenças em relação à Chat Completion API

Tratamento de erros

Exemplo de resposta de erro

Conclusão

​Processo de solicitação

​Uso básico

​Exemplo cURL

​Exemplo Python

​Prompt de sistema

​Exemplo Python

​Resposta em streaming

​Exemplo em Python

​Exemplo em JavaScript

​Conversas com múltiplas rodadas

​Exemplo em Python

​Modelo de raciocínio profundo

​Modelos visuais

​Usando imagens codificadas em Base64

​Usando imagens por URL

​Exemplo de cURL

​Documentos e PDF

​Cache de prompts

​Chamada de ferramentas (Tool Use)

​Exemplo em Python

​Diferenças em relação à Chat Completion API

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

Processo de solicitação

Uso básico

Exemplo cURL

Exemplo Python

Prompt de sistema

Exemplo Python

Resposta em streaming

Exemplo em Python

Exemplo em JavaScript

Conversas com múltiplas rodadas

Exemplo em Python

Modelo de raciocínio profundo

Modelos visuais

Usando imagens codificadas em Base64

Usando imagens por URL

Exemplo de cURL

Documentos e PDF

Cache de prompts

Chamada de ferramentas (Tool Use)

Exemplo em Python

Diferenças em relação à Chat Completion API

Tratamento de erros

Exemplo de resposta de erro

Conclusão