> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Solicitação e Uso da API Claude Messages

> Claude AI 集成指南 - XHuoAPI

Anthropic Claude é um sistema de diálogo AI muito poderoso, que pode gerar respostas fluentes e naturais em questão de segundos, apenas com a entrada de um prompt. A API Claude Messages é o formato nativo oficial da Anthropic, que, ao contrário do formato compatível da OpenAI (Chat Completion), adota uma estrutura de solicitação e resposta própria da Anthropic, permitindo melhor aproveitamento das capacidades únicas do Claude, como entrada de conteúdo multimodal, chamadas de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados.

Este documento descreve principalmente o fluxo de uso da API Claude Messages, permitindo que utilizemos uma interface nativa consistente com a oficial da Anthropic para acessar as funcionalidades de diálogo do Claude.

## Fluxo de Solicitação

Para usar a API Claude Messages, primeiro você pode acessar a página [Claude Messages API](https://api.xhuoapi.ai/documents/280928a2-2dce-419c-adb5-1ea835e8183a) e clicar no botão "Acquire" para obter as credenciais necessárias para a solicitação:

![](https://cdn.xhuoapi.ai/nyq0xz.png)

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual.

Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito dessa API.

## Uso Básico

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

* `model`: escolha o modelo Claude a ser utilizado, como `claude-opus-4-20250514`, `claude-sonnet-4-20250514`, etc.
* `messages`: array de mensagens de entrada, onde cada mensagem contém `role` (papel) 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 da resposta única.

Parâmetros opcionais comuns:

* `system`: prompt do sistema, usado para definir o comportamento e o papel do modelo.
* `temperature`: aleatoriedade da geração, entre 0-1, quanto maior o valor, mais dispersa a resposta.
* `stream`: se deve usar resposta em fluxo, configurado como `true` para obter um efeito de retorno palavra por palavra.
* `stop_sequences`: sequência de parada personalizada, o modelo parará de gerar ao encontrar esses textos.
* `top_p`: parâmetro de amostragem nuclear, que, em conjunto com a temperatura, controla a aleatoriedade da geração.
* `top_k`: amostra apenas entre as K opções com maior probabilidade.
* `tools`: definição de ferramentas, para permitir que o modelo chame funções externas.
* `tool_choice`: controla como o modelo usa as ferramentas fornecidas.

### Exemplo cURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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": "Hello, Claude"
      }
    ]
  }'
```

### Exemplo Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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, Claude"}
    ]
}

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

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

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

Descrição dos campos do resultado retornado:

* `id`: identificador único da mensagem atual.
* `type`: sempre será `message`.
* `role`: sempre será `assistant`.
* `content`: array de conteúdo da resposta, onde cada elemento contém `type` (como `text`) e o conteúdo correspondente.
* `model`: nome do modelo que processou a solicitação.
* `stop_reason`: razão da parada, os valores possíveis incluem `end_turn` (término normal), `max_tokens` (alcance do comprimento máximo), `stop_sequence` (encontro de sequência de parada), `tool_use` (chamada de ferramenta).
* `stop_sequence`: se a parada foi devido a uma sequência de parada personalizada, exibe o texto correspondente da sequência de parada.
* `usage`: estatísticas de uso de tokens, incluindo `input_tokens` (número de tokens de entrada) e `output_tokens` (número de tokens de saída).

## Prompt do Sistema

A API Claude Messages suporta a definição de prompts do sistema através do campo `system`, usado para definir o comportamento, papel e contexto do modelo.

### Exemplo Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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 de tradução profissional em chinês, por favor, traduza o inglês inserido pelo usuário para o 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 modo de atuação do Claude.

## Resposta em Fluxo

Esta interface também suporta resposta em fluxo, definindo o parâmetro `stream` como `true` para obter um efeito de retorno passo a passo, ideal para exibição palavra por palavra em uma página da web.

### Exemplo Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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 fluxo retorna no formato de Server-Sent Events (SSE), onde cada linha é precedida por `event:` e `data:`. Os tipos de eventos em fluxo incluem:

* `message_start`: início da mensagem, contendo informações básicas da mensagem e 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 novos trechos de texto gerados.
* `content_block_stop`: fim do bloco de conteúdo.
* `message_delta`: atualização incremental em nível de mensagem, contendo `stop_reason` e informações finais de `usage`.
* `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":"Oi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Meu nome é"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Como posso ajudá-lo hoje?"}}

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 a resposta em fluxo contém eventos `content_block_delta` que incluem o texto gerado passo a passo, e ao concatenar todos os `text_delta`, é possível obter a resposta completa.

### Exemplo em JavaScript

```javascript theme={null}
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: "Olá, Claude" }],
  }),
};

const response = await fetch("https://api.xhuoapi.ai/v1/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));
}
```

## Diálogo em várias rodadas

Se você deseja integrar a funcionalidade de diálogo em várias rodadas, deve alternar as mensagens dos papéis `user` e `assistant` no array `messages`, incluindo o histórico de conversas anteriores.

### Exemplo em Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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": "Olá, meu nome é Alice."},
        {"role": "assistant", "content": "Olá Alice! Prazer em conhecê-la. Como posso ajudá-la hoje?"},
        {"role": "user", "content": "Qual é o meu nome?"}
    ]
}

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

O resultado retornado é o seguinte:

```json theme={null}
{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Seu nome é Alice, como você acabou de me dizer!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}
```

Ao passar o histórico completo de conversas em `messages`, Claude pode fornecer respostas precisas com base no contexto.

## Modelo de Pensamento Profundo

Claude suporta a funcionalidade de Pensamento Estendido, que permite que o modelo realize raciocínios internos antes de responder, aumentando a precisão no tratamento de questões complexas. Para usar essa funcionalidade, é necessário passar o parâmetro `thinking`.

### Exemplo em Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Qual é o seno de 30 graus? Mostre seu raciocínio."}
    ]
}

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

O resultado retornado é o seguinte:

```json theme={null}
{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "O usuário está perguntando sobre o seno de 30 graus. Esta é uma questão básica de trigonometria.\n\nEm um triângulo 30-60-90, os lados estão na proporção 1:√3:2.\n\nPara um ângulo de 30°:\n- O lado oposto é 1\n- A hipotenusa é 2\n- Portanto, sen(30°) = oposto/hipotenusa = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "O seno de 30 graus é **1/2** ou **0.5**.\n\nEste é um dos valores trigonométricos fundamentais. Em um triângulo 30-60-90, os lados estão na proporção 1:√3:2, onde o lado oposto ao ângulo de 30° tem comprimento 1 e a hipotenusa tem comprimento 2, nos dando sen(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}
```

Pode-se ver que o array `content` contém dois blocos de conteúdo:

* `type: "thinking"`: o processo de pensamento interno do modelo, mostrando os passos de raciocínio.
* `type: "text"`: o resultado final da resposta.

Observações:

* Ao usar `thinking`, `max_tokens` deve ser maior que `budget_tokens`, pois `budget_tokens` é o orçamento de tokens alocado para o processo de pensamento.
* Quanto maior o `budget_tokens`, maior será o espaço para o modelo realizar um raciocínio mais profundo, adequado para lidar com questões complexas.

## Modelo Visual

Claude suporta entrada multimodal, podendo processar texto e imagens simultaneamente. Na API de Mensagens, você pode usar a capacidade visual definindo `content` como um formato de array e incluindo blocos de conteúdo de imagem.

### Usando Imagem Codificada em Base64

```python theme={null}
import base64
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

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

# Lendo e codificando a imagem
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": "O que há nesta imagem?"
                }
            ]
        }
    ]
}

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

### Usando Imagem por URL

```python theme={null}
# Exemplo de uso de imagem por URL
```

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "O que há nesta imagem?"
                }
            ]
        }
    ]
}

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

### Exemplo de cURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "O que há nesta imagem?"
          }
        ]
      }
    ]
  }'
```

Formatos de imagem suportados incluem: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.

Exemplo de resultado retornado:

```json theme={null}
{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Esta imagem mostra uma interface de configuração de requisição de API para o que parece ser um serviço de conclusão de chat de IA. A interface inclui parâmetros para seleção de modelo, mensagens, modo de streaming e configurações de tokens máximos."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}
```

## Chamada de Ferramenta (Tool Use)

A API de Mensagens do Claude suporta nativamente a funcionalidade de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções pré-definidas quando necessário.

### Exemplo em Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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": "Obter o clima atual em uma determinada localização",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A cidade e estado, por exemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Como está o clima em San Francisco?"}
    ]
}

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

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

```json theme={null}
{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Deixe-me verificar o clima em San Francisco para você."
    },
    {
      "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
  }
}
```

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

```python theme={null}
payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obter o clima atual em uma determinada localização",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A cidade e estado, por exemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Como está o clima em San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Deixe-me verificar o clima em San Francisco para você."},
                {"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": "Ensolarado, 22°C"
                }
            ]
        }
    ]
}

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ça em Relação à API de Conclusão de Chat

A XHuoAPI oferece dois formatos de API do Claude, e as principais diferenças são as seguintes:

| Característica         | API de Mensagens (`/v1/messages`)      | API de Conclusão de Chat (`/v1/chat/completions`)              |
| ---------------------- | -------------------------------------- | -------------------------------------------------------------- |
| Formato                | Formato nativo da Anthropic            | Formato compatível com OpenAI                                  |
| Prompt do sistema      | Campo `system` independente            | Passado através de `messages` com `role: "system"`             |
| Estrutura de resposta  | Array `content` (suporta vários tipos) | Array `choices` (contém `message`)                             |
| Formato de streaming   | Eventos SSE (vários tipos de eventos)  | Linhas SSE `data`                                              |
| Pensamento profundo    | Parâmetro `thinking` nativo            | Acionado por nome de modelo especial (como sufixo `-thinking`) |
| Chamada de ferramentas | `tools` nativo + `input_schema`        | Formato `functions` compatível com OpenAI                      |
| Estatísticas de Token  | `input_tokens` / `output_tokens`       | `prompt_tokens` / `completion_tokens`                          |

Se o seu sistema já estiver integrado ao formato da API do OpenAI, você pode usar a API de Conclusão de Chat para uma transição suave. Se você precisar usar todas as capacidades nativas do Claude, recomenda-se usar a API de Mensagens.

## Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:

* `400 token_mismatched`: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `400 api_not_implemented`: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `401 invalid_token`: Não autorizado, token de autorização inválido ou ausente.
* `429 too_many_requests`: Muitas requisições, você excedeu o limite de taxa.
* `500 api_error`: Erro interno do servidor, algo deu errado no servidor.

### Exemplo de Resposta de Erro

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusão

Através deste documento, você já entendeu como usar a API de Mensagens Claude para chamar a funcionalidade de conversa do Claude no formato nativo da Anthropic. A API de Mensagens suporta uma variedade de recursos, como conversas básicas, prompts de sistema, respostas em fluxo, diálogos de múltiplas rodadas, pensamento profundo, compreensão visual e chamadas de ferramentas. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.