Solicitação e uso da API Claude Chat Completion

O Anthropic Claude é um sistema de conversação com IA muito poderoso que, basta inserir um prompt, pode gerar respostas fluentes e naturais em apenas alguns segundos. Claude se destaca no setor por sua excelente capacidade de compreensão e geração de linguagem. Atualmente, Claude já é amplamente utilizado em vários setores e áreas, e sua influência é cada vez mais significativa. Seja em conversas diárias, escrita criativa, consultas profissionais ou programação de código, Claude pode fornecer assistência inteligente surpreendente, aumentando enormemente a eficiência de trabalho e a criatividade humanas. Este documento apresenta principalmente o fluxo de uso das operações da API Claude Chat Completion. Com ela, podemos usar facilmente a funcionalidade de conversa do Claude oficial.

Processo de solicitação

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

Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login para se registrar e entrar, e, após a conclusão, retornará automaticamente à página atual. Um API Token pode chamar todos os serviços da plataforma, sem a necessidade de solicitar separadamente para cada serviço. A primeira solicitação oferece créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo universal no console.

📘 Documentação completa: Claude Chat Completion API →

Uso básico

Em seguida, você pode preencher o conteúdo correspondente na interface, conforme mostrado na imagem:

Ao usar essa interface pela primeira vez, precisamos preencher pelo menos três conteúdos. Um deles é authorization, que pode ser selecionado diretamente na lista suspensa. Outro parâmetro é model, sendo recomendado usar o mais recente modelo principal claude-fable-5-1; o antigo claude-fable-5 ainda pode continuar sendo chamado. O último parâmetro é messages, que é um array de prompts de pergunta, e cada elemento contém role e content; role suporta user, assistant, system, e content é o conteúdo específico. Claude Fable 5.1 suporta contexto de 1 milhão de Tokens e saída máxima de 128K Tokens. Ao mesmo tempo, você pode observar que há geração do código de chamada correspondente à direita. Você pode copiar o código e executá-lo diretamente, ou clicar diretamente no botão «Try» para testar. Parâmetros opcionais comuns:

max_tokens: limita o número máximo de tokens em uma única resposta.
temperature: aleatoriedade da geração, entre 0 e 2; quanto maior o valor, mais disperso será.
n: quantas respostas candidatas gerar de uma vez.
response_format: configuração do formato de retorno.

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

{
  "id": "msg_bdrk_01Q6WN27v95ypCa1kbanAQ6K",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "created": 1768619365,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

O resultado retornado possui vários campos, apresentados a seguir:

id, o ID da tarefa de conversa gerada desta vez, usado para identificar exclusivamente esta tarefa de conversa.
model , o modelo Claude oficial selecionado.
choices, as informações de resposta fornecidas pelo Claude para o prompt de pergunta.
usage : informações estatísticas sobre tokens para esta sessão de perguntas e respostas.

No formato Chat Completions, usage.prompt_tokens é o total de entrada; prompt_tokens_details.cached_tokens e prompt_tokens_details.cache_write_tokens registram, respectivamente, os detalhes de leitura e gravação de cache. completion_tokens_details.reasoning_tokens é um subconjunto de completion_tokens; não os some novamente ao calcular o total ou o custo. Respostas não stream também podem retornar o objeto usage.cost, no qual amount é o consumo real de créditos, currency é a unidade de medida, e list_amount é o valor antes do desconto (se houver). O nome do campo compatível com Chat é reasoning_tokens; a API Messages nativa usa output_tokens_details.thinking_tokens. O wire schema dos dois protocolos é diferente, e o cliente não deve misturar os nomes dos campos. Entre eles, choices contém as informações de resposta do Claude, e os choices dentro dele são as informações específicas da resposta do Claude, como pode ser visto na imagem.

Pode-se ver que o campo content dentro de choices contém o conteúdo específico da resposta do Claude.

Resposta em streaming

Essa interface também oferece suporte a respostas em streaming, o que é muito útil para integração com páginas web, permitindo que a página web implemente o efeito de exibição caractere por caractere. Se desejar retornar respostas em streaming, você pode alterar o parâmetro stream no cabeçalho da solicitação para true. A modificação é mostrada na imagem, mas o código de chamada precisa ser alterado correspondentemente para oferecer suporte à resposta em streaming.

Após modificar stream para true, a API retornará os dados JSON correspondentes linha por linha. No nível do código, precisamos fazer as modificações correspondentes para obter os resultados linha por linha. Código de chamada de exemplo em Python:

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

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

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

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

O efeito da saída é o seguinte:

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": ""}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "Hello!"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " How can I help you"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " today?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20, "prompt_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 0}}}

data: [DONE]

É possível ver que há muitos data na resposta, e os choices dentro de data são o conteúdo mais recente da resposta, consistente com o conteúdo apresentado acima. choices é o novo conteúdo da resposta, e você pode integrá-lo ao seu sistema com base nos resultados. Ao mesmo tempo, o fim da resposta em streaming é determinado pelo conteúdo de data; se o conteúdo for [DONE], isso indica que a resposta em streaming foi totalmente concluída. O resultado data retornado possui vários campos, apresentados a seguir:

id, o ID da tarefa desta conversa gerada, usado para identificar exclusivamente esta tarefa de conversa.
model , o modelo oficial do Claude selecionado.
choices, as informações de resposta fornecidas pelo Claude para a pergunta.

JavaScript também é compatível, por exemplo, o código de chamada em streaming do Node.js é o seguinte:

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

fetch("https://api.acedata.cloud/v1/chat/completions", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

Código de exemplo em Java:

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "claude-opus-4-20250514");
jsonObject.put("messages", [{"role":"user","content":"Hello"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/v1/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())

Outras linguagens podem ser adaptadas separadamente, o princípio é o mesmo.

Conversa com múltiplas rodadas

Se você quiser integrar a funcionalidade de conversa com múltiplas rodadas, precisará enviar várias perguntas no campo messages; exemplos específicos de várias perguntas são mostrados na imagem abaixo:

Código de chamada de exemplo em Python:

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

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

payload = {
    "model": "claude-opus-4-20250514",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello! How can I help you today?"},{"role":"user","content":"What I say just now?"}]
}

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

Ao enviar várias perguntas, é possível implementar facilmente uma conversa com múltiplas rodadas e obter a seguinte resposta:

{
  "id": "msg_bdrk_01Y1wfQmd89g968TVbFu57Yc",
  "model": "claude-opus-4-20250514",
  "object": "chat.completion",
  "created": 1768619674,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You said \"Hello\" - that was your first message to me in our conversation."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 20,
    "total_tokens": 49,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

É possível ver que as informações contidas em choices são consistentes com o conteúdo do uso básico; isso contém o conteúdo específico da resposta do Claude para várias conversas, permitindo assim responder às perguntas correspondentes com base em vários conteúdos de conversa.

Pensamento profundo

Os modelos Claude de nova geração podem realizar raciocínio de acordo com a estratégia padrão do modelo, sem a necessidade de acioná-lo por meio do sufixo de modelo -thinking. As respostas compatíveis com Chat usam o campo de usage compatível com OpenAI completion_tokens_details.reasoning_tokens. reasoning_tokens já está incluído em completion_tokens, não o some novamente. O raciocínio e o corpo visível compartilham o limite de tokens de saída, portanto, quando max_tokens for pequeno, o corpo pode ficar vazio ou ser truncado; nesse caso, aumente o orçamento de saída ou, quando o modelo utilizado oferecer suporte, escolha um nível menor de esforço de raciocínio. Se precisar de thinking nativo, output_config.effort, blocos de conteúdo thinking e retorno de assinatura, use /v1/messages. O campo usage correspondente a Messages é output_tokens_details.thinking_tokens; não o misture com completion_tokens_details.reasoning_tokens compatível com Chat.

Modelos visuais

claude-sonnet-4-20250514 é um modelo multimodal de linguagem de grande porte desenvolvido pela Claude, que adiciona capacidades de compreensão visual com base no claude-4. Este modelo pode processar simultaneamente entradas de texto e imagem, alcançando compreensão e geração multimodais. O processamento de texto usando o modelo claude-sonnet-4-20250514 é consistente com o conteúdo básico de uso acima; a seguir, será apresentada brevemente a forma de usar a capacidade de processamento de imagens do modelo. A capacidade de processamento de imagens usando o modelo claude-sonnet-4-20250514 é obtida principalmente adicionando um campo type com base no conteúdo content original. Por meio desse campo, é possível saber se o que foi enviado é texto ou imagem, usando assim a capacidade de processamento de imagens do modelo claude-sonnet-4-20250514. A seguir, é descrito principalmente como chamar essa funcionalidade usando Curl e Python.

Método de script Curl

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

Método de script Python

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

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

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

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

Em seguida, é possível obter o resultado abaixo. As informações dos campos no resultado são consistentes com as descritas acima, especificamente como segue:

{
  "id": "msg_bdrk_01NCrxpZmV17bhQJJRQEFEb9",
  "model": "claude-sonnet-4-20250514",
  "object": "chat.completion",
  "created": 1768628904,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Esta imagem mostra uma interface de configuração de solicitação de API para o que parece ser um serviço de conclusão de chat de IA. Aqui estão os elementos principais:\n\n**Parâmetros do corpo da solicitação:**\n\n1. **model** (string obrigatória) - Definido como \"claude-opus-4-202505...\" - especifica qual modelo de IA usar\n\n2. **messages** (array obrigatório) - Contém o histórico da conversa com:\n   - **role** (string obrigatória) - Definido como \"user\" \n   - **content** (string obrigatória) - Contém \"Hello\" como conteúdo da mensagem\n\n3. **stream** (booleano) - Definido como \"true\" - habilita deltas parciais de mensagens como no ChatGPT\n\n4. **max_tokens** (número) - Campo para definir o máximo de tokens que podem ser gerados na resposta\n\n5. **n** (número) - Especifica quantas opções de conclusão de chat gerar para cada entrada\n\nA interface possui um tema escuro com texto branco em fundos pretos/cinza-escuros. Há um botão \"Fill Example\" no canto inferior direito e vários menus suspensos e campos de entrada para configurar os parâmetros da solicitação de API. Um ícone vermelho de lixeira/exclusão está visível, provavelmente para remover entradas de mensagem."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1570,
    "completion_tokens": 252,
    "total_tokens": 1822,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

É possível ver que o conteúdo da resposta é baseado na imagem, portanto, por meio das duas formas acima, é possível usar facilmente as capacidades de processamento de texto e imagem do modelo claude-3-7-sonnet-20250219.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações de erro correspondentes. Por exemplo:

400 token_mismatched：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented：Solicitaçã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 solicitações, você excedeu o limite de taxa.
500 api_error：Erro interno do servidor, algo deu errado no servidor.

Exemplo de resposta de erro

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

Conclusão

Por meio deste documento, você já aprendeu como usar a Claude Chat Completion API para implementar facilmente a funcionalidade de conversa do Claude oficial. Esperamos que este documento possa ajudá-lo a integrar e utilizar melhor essa API. 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 Chat Completion

Processo de solicitação

Uso básico

Resposta em streaming

Conversa com múltiplas rodadas

Pensamento profundo

Modelos visuais

Tratamento de erros

Exemplo de resposta de erro

Conclusão

​Processo de solicitação

​Uso básico

​Resposta em streaming

​Conversa com múltiplas rodadas

​Pensamento profundo

​Modelos visuais

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

Processo de solicitação

Uso básico

Resposta em streaming

Conversa com múltiplas rodadas

Pensamento profundo

Modelos visuais

Tratamento de erros

Exemplo de resposta de erro

Conclusão