API Chat Completions: como funciona e como usar

Entenda como a API Chat Completions funciona, aprenda a integrá-la ao Python, conheça os principais parâmetros, o streaming e as chamadas de ferramentas e descubra como provedores compatíveis com OpenAI, como a Kimi API, podem viabilizar o desenvolvimento flexível de aplicações de IA.

Tempo de leitura: 9 minutosAtualizado: 2026-11-14

Experimente a Kimi API

Fluxo de solicitação e resposta da API Chat Completions

Seja para criar um chatbot de IA ou adicionar recursos conversacionais a uma aplicação, é importante entender como a IA lida com conversas. A API Chat Completions torna isso possível ao conectar aplicações a modelos de IA para gerar respostas relevantes e semelhantes às humanas. Com recursos como integração com Python, streaming e chamadas de ferramentas, os desenvolvedores podem criar aplicações mais interativas. Veja como ela funciona, como usá-la e como provedores como a Kimi API oferecem suporte ao desenvolvimento flexível de IA.

O que é a API Chat Completions

A API Chat Completions é uma interface que permite que aplicações enviem uma sequência de mensagens a um modelo de IA e recebam uma resposta do assistente, oferecendo suporte a conversas de uma ou várias interações. Por exemplo, você pode usar o Kimi K3.1 Pro para responder a uma pergunta sobre decoradores em Python e depois fazer uma pergunta complementar:

Primeira solicitação: envie a mensagem do usuário: "O que é um decorador em Python?" A Kimi retorna uma mensagem do assistente explicando o conceito.
Segunda solicitação: para continuar a conversa, envie a mensagem anterior do usuário, a mensagem completa do assistente da Kimi e uma nova mensagem do usuário: "Você pode me dar um exemplo?"

A matriz messages contém o contexto necessário para cada solicitação. Três decisões de projeto importantes tornam essa interface amplamente adotada:

Histórico gerenciado pela aplicação: as aplicações gerenciam o histórico da conversa e incluem o contexto relevante em cada solicitação, dando aos desenvolvedores controle sobre o que o modelo vê.
Funções comuns das mensagens: As funções mais comuns incluem system (instruções), user (entrada), assistant (saída do modelo, reenviada para manter o contexto em conversas com várias interações) e tool (resultados de chamadas de função). Juntas, elas ajudam a expressar instruções, diálogos e interações com ferramentas.
Recursos flexíveis: Dependendo do suporte do modelo, a interface pode lidar com streaming, chamadas de ferramentas, entradas visuais e saídas estruturadas. Kimi K3.1 Pro oferece suporte a esses recursos.

Como usar a API Chat Completions com Kimi

Os exemplos a seguir usam Kimi K3.1 Pro e o SDK Python da OpenAI para demonstrar como configurar o cliente, enviar solicitações, processar respostas e implementar chamadas de ferramentas:

Início rápido: chame Kimi com o SDK Python da OpenAI

Instale o SDK Python da OpenAI:

pip install --upgrade openai

Defina sua chave da Kimi API como uma variável de ambiente:

export MOONSHOT_API_KEY="sk-your-kimi-key"

Você não precisa de uma chave da API da OpenAI. O SDK Python da OpenAI atua como biblioteca cliente, enquanto sua chave da Kimi API e a URL base autenticam e direcionam as solicitações para Kimi.

Inicialize o cliente e envie sua primeira solicitação:

import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1", ) resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Explain REST in one paragraph."} ], ) print(resp.choices[0].message.content)

Este exemplo usa o endpoint internacional da Kimi API. Para conferir a configuração oficial e os detalhes do modelo, consulte o Início rápido do Kimi K3.1 Pro.

Principais parâmetros

Estes parâmetros abrangem as principais opções disponíveis ao chamar Kimi K3.1 Pro pela API Chat Completions:

Parâmetro	Finalidade
`model`	Especifica o ID do modelo, como `kimi-k3.1-pro`.
`messages`	Fornece mensagens da conversa, incluindo entradas anteriores do usuário e respostas do assistente. Aceita conteúdo textual e multimodal.
`reasoning_effort`	Controla a profundidade do raciocínio. Aceita `low`, `high` ou `max` (padrão).
`max_completion_tokens`	Define o limite máximo de geração, incluindo tanto os tokens de raciocínio quanto os tokens da resposta final. Os tokens de entrada são contabilizados separadamente, mas o total de tokens de entrada e de tokens gerados deve caber na janela de contexto do modelo.
`stream`	Defina como `true` para receber a resposta gradualmente, em vez de esperar pela saída completa.
`tools`	Define funções que o modelo pode solicitar que a aplicação execute.
`response_format`	Controla a formatação da saída. Aceita `json_object` para o modo JSON e `json_schema` para saída estruturada com restrições de esquema.

Observação: Kimi K3.1 Pro usa configurações fixas de amostragem. Não adicione temperature nem top_p às solicitações. Consulte a referência da API Chat Completions para ver detalhes dos parâmetros e valores compatíveis.

Como ler a resposta

Após uma solicitação bem-sucedida, você pode acessar os principais campos da resposta por meio do objeto de conclusão retornado:

choices[0].message – Contém a resposta do assistente, incluindo content ou tool_calls quando o modelo solicita uma função.
choices[0].finish_reason – Indica por que a geração foi interrompida, como stop, length ou tool_calls.
usage – Fornece informações sobre o uso de token, incluindo as contagens de token de entrada, saída e cache, quando disponíveis.

Para uma resposta de texto básica, leia choices[0].message.content. Se o modelo retornar tool_calls, sua aplicação deverá executar as funções solicitadas e enviar os resultados em uma solicitação de acompanhamento

Exemplo de streaming

Defina stream=True para receber a resposta de Kimi em partes incrementais. O exemplo a seguir reutiliza o client configurado acima e imprime a resposta final à medida que ela chega:

stream = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Write a haiku about autumn."} ], stream=True, ) for chunk in stream: if not chunk.choices: continue delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True)

Kimi K3.1 Pro retorna o conteúdo de raciocínio separadamente da resposta final. Este exemplo imprime apenas delta.content, portanto exibe a resposta final sem processar o campo separado reasoning_content.

Chamadas de ferramentas em resumo

As chamadas de ferramentas permitem que Kimi solicite funções externas quando uma tarefa exige informações ou ações que vão além da própria resposta do modelo. Por exemplo, se um usuário perguntar: "Devo levar um guarda-chuva em Tóquio hoje?", Kimi poderá solicitar uma função get_weather para obter a previsão.

O fluxo de trabalho tem três etapas:

Declare a função: Defina get_weather e os argumentos esperados no parâmetro tools.
Execute a ferramenta: Kimi retorna uma entrada tool_calls com o nome da função e os argumentos. Sua aplicação executa a função correspondente e obtém os dados meteorológicos.
Envie o resultado de volta: Adicione à conversa a mensagem completa do assistente de Kimi e o resultado da ferramenta (usando o tool_call_id correspondente); em seguida, chame Kimi novamente para gerar uma resposta voltada ao usuário.

O exemplo a seguir reutiliza o client configurado acima. Antes de executá-lo, certifique-se de ter implementado uma função get_weather(city) que retorne dados meteorológicos serializáveis em JSON. A função é executada pela sua aplicação, não por Kimi.

import json tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get the weather forecast for a city.", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } } ] messages = [ {"role": "user", "content": "Should I bring an umbrella in Tokyo today?"} ] # Ask Kimi whether it needs to call a tool resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) assistant_message = resp.choices[0].message # Preserve the complete assistant message, including tool_calls messages.append(assistant_message) # Execute the requested function in your application for tool_call in assistant_message.tool_calls or []: if tool_call.function.name == "get_weather": args = json.loads(tool_call.function.arguments) # Call your own weather service or API weather_result = get_weather(city=args["city"]) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(weather_result) }) # Let Kimi interpret the tool result and answer the user final_resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) print(final_resp.choices[0].message.content)

Aqui, get_weather() representa uma função implementada pela sua aplicação, não uma função executada diretamente por Kimi. Kimi decide quando solicitá-la e fornece os argumentos; sua aplicação executa a operação e retorna o resultado.

Em produção, implemente um loop que processe cada chamada de ferramenta, adicione os resultados correspondentes à conversa e envie as mensagens atualizadas de volta para Kimi. Repita esse ciclo até que o modelo retorne uma resposta final sem solicitar ferramentas adicionais.

Por que a compatibilidade com a OpenAI importa ao escolher um provedor

Muitos provedores oferecem suporte ao formato OpenAI Chat Completions, permitindo que desenvolvedores reutilizem SDKs e estruturas de solicitação conhecidos. Em geral, a migração envolve atualizar a URL base, a chave da API e o ID do modelo e, depois, verificar os parâmetros compatíveis e o processamento das respostas. Ao comparar provedores, considere os seguintes fatores:

Fidelidade de compatibilidade: Verifique se streaming, chamadas de ferramentas, saídas estruturadas e relatórios de usage funcionam como sua aplicação espera. A compatibilidade com o mesmo formato de API não garante suporte idêntico a recursos nem o mesmo comportamento de resposta entre provedores.
Qualidade do modelo para sua carga de trabalho: A combinação de idiomas e os tipos de tarefa são mais importantes do que benchmarks genéricos.
Janela de contexto: Modelos de contexto longo podem simplificar alguns fluxos de trabalho com documentos ao processar mais material de origem em uma única solicitação.
Estrutura de custos: O cache e os descontos por lote frequentemente têm mais impacto do que os preços por token anunciados.
Amplitude do ecossistema: Endpoints compatíveis adicionais, como Responses e Anthropic Messages, podem oferecer mais opções de integração e flexibilidade à medida que sua aplicação evolui.

Kimi API: um provedor compatível com a OpenAI que se destaca

A Kimi API, desenvolvida pela Moonshot AI, vale ser considerada se você procura um provedor compatível com a OpenAI, especialmente para aplicações em chinês, processamento de documentos longos e agentes de programação. Ela combina padrões conhecidos de integração de API com os recursos de contexto longo e raciocínio de Kimi.

Compatibilidade imediata

Se sua aplicação já usa o SDK Python da OpenAI, você pode integrar o Kimi sem reescrever todo o fluxo de solicitações. Basta atualizar a configuração da API, incluindo base_url, api_key e o ID do modelo, mantendo a interface conhecida de Chat Completions.

Por exemplo, o código a seguir lê um relatório local de report.txt, envia seu conteúdo ao Kimi K3.1 Pro para gerar um resumo e transmite a resposta gerada em streaming:

from pathlib import Path report_text = Path("report.txt").read_text(encoding="utf-8") resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ { "role": "user", "content": f"Summarize the following report:\n\n{report_text}" } ], stream=True, ) for chunk in resp: if not chunk.choices: continue content = chunk.choices[0].delta.content if content: print(content, end="", flush=True)

Aqui, o client reutiliza o cliente Kimi inicializado anteriormente com sua chave de API, lida de uma variável de ambiente. Escolha a URL base de acordo com sua região: https://api.moonshot.ai/v1 para a plataforma internacional ou https://api.moonshot.cn/v1 para usuários que acessam a API na China continental.

Essa abordagem permite manter seu fluxo de trabalho atual com o SDK da OpenAI enquanto usa modelos Kimi em tarefas como resumo de documentos e outras aplicações baseadas em API.

Diferenciais do Kimi

Um modelo principal com janela de contexto de 1 milhão de tokens: o Kimi K3.1 Pro oferece uma janela de contexto de até 1 milhão de tokens e compreensão visual nativa. Desenvolvedores podem trabalhar com grandes bases de código, documentos do tamanho de livros e entradas de imagem em um único fluxo de trabalho, o que o torna adequado para raciocínio complexo, programação e aplicações multimodais.
Otimização flexível de custos: a Kimi API oferece cache automático de contexto para prefixos de solicitações repetidos e inferência por Batch API para tarefas em grande escala que não exigem respostas em tempo real. A cobrança do cache e os preços do Batch dependem do modelo e das regras de preço aplicáveis. Consulte os preços oficiais da Kimi API para ver as tarifas atuais e os detalhes de cobrança.
Compatibilidade entre ecossistemas de API: o Kimi fornece endpoints de Chat Completions e Responses API compatíveis com OpenAI, além de um endpoint compatível com Anthropic Messages. Desenvolvedores podem integrar o Kimi K3.1 Pro a fluxos de trabalho existentes usando SDKs e formatos de API conhecidos, com ajustes conforme o endpoint e os recursos compatíveis.

Conclusão

Começar a usar a Chat Completions API é simples: configure suas credenciais de API, envie uma solicitação e leia a resposta gerada em choices[0].message.content. Quando sua primeira chamada de API estiver funcionando, você poderá ampliar a integração de acordo com as necessidades da sua aplicação, adicionando conversas com múltiplos turnos, respostas em streaming ou chamada de ferramentas. Pronto para desenvolver com Kimi? Obtenha sua chave da Kimi API e comece a fazer solicitações de API.

Experimente a Kimi API

Perguntas frequentes

Não. A API Chat Completions não é exclusiva dos modelos OpenAI. Outros provedores de IA, incluindo a Kimi, oferecem APIs compatíveis com o formato Chat Completions da OpenAI. Isso permite que desenvolvedores reutilizem SDKs e estruturas de solicitação já conhecidas com modelos compatíveis de diferentes provedores, embora o suporte a recursos possa variar.

As duas APIs permitem que aplicações interajam com modelos de IA, mas usam estruturas diferentes de solicitação e resposta. A API Chat Completions usa uma matriz messages e retorna respostas em uma matriz choices. A API Responses usa uma estrutura de entrada e saída mais flexível, compatível com diferentes tipos de conteúdo e interações com ferramentas. O gerenciamento do estado da conversa varia conforme o provedor. Com a API Responses da Kimi, as aplicações devem incluir o histórico relevante da conversa em cada solicitação, em vez de depender do encadeamento por ID de resposta.

Se sua aplicação usa o SDK da OpenAI, geralmente é possível migrar para a Kimi atualizando três valores de configuração: base_url para o endpoint da Kimi API, api_key para sua chave da Kimi API e model para o ID de um modelo Kimi compatível. Em seguida, teste a integração para verificar se os parâmetros e recursos dos quais sua aplicação depende, como streaming e chamadas de ferramentas, são compatíveis.