OpenAI Chat Completions API: guia de recursos e uso

Criar uma aplicação com IA não se resume a fazer um modelo gerar respostas. Também é preciso ter uma forma confiável de gerenciar conversas, orientar respostas e conectar tudo à sua aplicação. A API Chat Completions da OpenAI torna isso possível ao dar aos desenvolvedores controle sobre como a IA lida com mensagens e gera respostas. Se você quer entender como ela funciona e como usá-la em seus próprios projetos, este artigo apresentará tudo o que você precisa saber.

A API Chat Completions da OpenAI permite que desenvolvedores integrem os modelos de linguagem da OpenAI a aplicações e serviços. Ela gera respostas a partir de uma sequência de mensagens e oferece suporte a tarefas como conversação, resposta a perguntas, geração de conteúdo e análise de texto.

O Chat Completions continua sendo compatível. Para novos projetos, a OpenAI recomenda a API Responses. Este guia se concentra no Chat Completions para explicar seu formato de mensagens, parâmetros de solicitação e uso com SDKs compatíveis.

Ao contrário do endpoint legado Completions (/v1/completions), que aceita um prompt de texto, o Chat Completions aceita uma lista estruturada de mensagens. Cada mensagem tem uma função, como developer, user ou assistant, que ajuda o modelo a interpretar as instruções e o contexto da conversa. As funções e os tipos de conteúdo compatíveis dependem do modelo selecionado.

Os desenvolvedores podem usar a API para criar vários recursos com IA, incluindo:

• Aplicações conversacionais: Crie chatbots de IA, assistentes virtuais e sistemas de suporte ao cliente que respondem às mensagens dos usuários.

• Geração de conteúdo: Gere artigos, descrições de produtos, e-mails, resumos e outros conteúdos escritos.

• Análise de texto: Classifique textos, extraia informações, analise sentimentos e identifique pontos-chave em documentos.

• Assistência para programação: Gere trechos de código, explique conceitos de programação e ajude desenvolvedores a solucionar erros.

• Processamento de linguagem: Traduza, reescreva, simplifique e revise textos em diferentes idiomas.

A API oferece uma forma flexível de conectar modelos de linguagem a softwares existentes, permitindo que desenvolvedores incorporem respostas geradas por IA às suas aplicações sem precisar criar e hospedar seus próprios modelos de linguagem.

A API Chat Completions segue um fluxo de solicitação e resposta. Uma aplicação envia ao endpoint da API uma solicitação que contém um identificador de modelo e uma lista de mensagens. O modelo selecionado processa a entrada e retorna uma resposta gerada.

O fluxo básico inclui as seguintes etapas:

1. Prepare a conversa: A aplicação coleta a entrada do usuário e a organiza em uma lista de mensagens. Mensagens anteriores da conversa também podem ser incluídas para fornecer contexto.

2. Envie uma solicitação à API: A aplicação envia uma solicitação POST para https://api.openai.com/v1/chat/completions com o modelo selecionado e a lista de mensagens. As solicitações usam o cabeçalho Authorization: Bearer <API_KEY>. O método client.chat.completions.create() do SDK Python lida com essa estrutura de solicitação e a autenticação.

3. Processe a entrada: O modelo interpreta as mensagens, considera suas funções e conteúdos e gera uma resposta com base no contexto e nos parâmetros fornecidos.

4. Receba a resposta: Uma solicitação sem streaming retorna uma resposta JSON contendo a resposta gerada e metadados. Com o streaming ativado, a API envia uma sequência de eventos enviados pelo servidor (SSE), que a aplicação processa à medida que chegam.

5. Exiba ou processe a saída: A aplicação extrai a mensagem gerada e a exibe ao usuário ou a encaminha para outro componente da aplicação.

O fluxo se baseia no modelo de solicitação e resposta da API Chat Completions da OpenAI.

Para usar a API Chat Completions de forma eficaz, os desenvolvedores precisam entender seus principais parâmetros de solicitação e como eles afetam o comportamento do modelo.

O parâmetro model especifica qual modelo de linguagem processa a solicitação. Modelos diferentes podem oferecer diferentes recursos, velocidades de resposta, desempenho de raciocínio e preços.

Os desenvolvedores devem selecionar um modelo de acordo com a complexidade da tarefa, a qualidade esperada da resposta, os requisitos de latência e o orçamento.

O parâmetro messages contém uma matriz de mensagens da conversa. Cada mensagem normalmente inclui os campos role e content.

As funções mais comuns incluem:

Escolha a função de instrução compatível com seu modelo; não é necessário enviar mensagens system e developer com as mesmas instruções. Para manter o contexto entre interações, inclua o histórico relevante da conversa em cada solicitação. Provedores compatíveis podem oferecer suporte a funções diferentes; portanto, siga a documentação de modelo de cada um ao adaptar uma integração.

Nos modelos e configurações que oferecem suporte a ele, temperature controla a aleatoriedade da amostragem. A referência da API define um intervalo de 0 a 2, com padrão de 1. Verifique o suporte a parâmetros do modelo selecionado antes de definir um valor personalizado.

• Temperatura mais baixa: Produz respostas mais focadas e previsíveis, o que a torna útil para classificação, extração de informações e tarefas estruturadas.

• Temperatura mais alta: Permite mais variação no texto gerado, o que pode ser útil para brainstorming e escrita criativa.

Algumas configurações de raciocínio não aceitam valores personalizados de temperature ou top_p. Nessas configurações, omita esses parâmetros de amostragem e use controles compatíveis, como esforço de raciocínio e limites de saída.

Quando compatível, top_p controla a seleção de tokens por meio da amostragem por núcleo. Ele define o limite de probabilidade cumulativa usado para escolher os tokens candidatos.

Por exemplo, um valor de 0,1 significa que o modelo considera tokens dentro dos 10% mais altos da massa de probabilidade cumulativa. Em geral, valores menores produzem resultados mais focados, enquanto valores maiores permitem mais variação.

A OpenAI recomenda ajustar temperature ou top_p, em vez de alterar ambos simultaneamente.

O parâmetro max_completion_tokens define o número máximo de tokens que o modelo pode gerar em uma resposta, incluindo tokens de raciocínio, quando aplicável.

Definir um limite adequado ajuda os desenvolvedores a controlar o comprimento da saída e gerenciar o consumo de tokens. Se o modelo atingir esse limite antes de concluir a resposta, a conclusão poderá terminar com o motivo de finalização length.

O parâmetro stream determina se a API retorna a resposta gerada de uma só vez ou progressivamente à medida que ela é produzida.

• false: Retorna a resposta completa após o término da geração.

• true: Transmite os dados da resposta para a aplicação por meio de eventos enviados pelo servidor (SSE).

A transmissão é útil para interfaces de chat e aplicações nas quais os usuários se beneficiam de ver as respostas surgirem progressivamente, em vez de esperar pela saída completa.

O parâmetro response_format seleciona o formato de saída em modelos compatíveis. Texto é o padrão. Definir type como json_object ativa o modo JSON, que produz JSON válido, mas não impõe um esquema específico. Inclua nas mensagens uma instrução para retornar JSON.

Para campos e tipos de dados previsíveis, use Saídas Estruturadas baseadas em JSON Schema com type: "json_schema" e strict: true em um modelo compatível. Apenas o subconjunto compatível de JSON Schema pode ser usado no modo estrito. Antes de processar o resultado, verifique se houve recusa ou se a resposta foi truncada. Consulte o guia de Saídas Estruturadas para ver detalhes de configuração.

O parâmetro tool_choice controla a seleção de ferramentas quando o modelo oferece suporte à chamada de ferramentas por meio de Chat Completions. O suporte depende tanto do modelo quanto da configuração de raciocínio; alguns modelos mais recentes exigem a Responses API para usar ferramentas. Verifique esses requisitos antes de adicionar ferramentas a uma solicitação.

As configurações comuns incluem:

• none: Impede que o modelo chame ferramentas.

• auto: Permite que o modelo decida se deve chamar uma ferramenta disponível.

• required: Exige que o modelo chame uma ou mais ferramentas.

Esse recurso oferece suporte à chamada de funções, permitindo que uma aplicação conecte decisões geradas pelo modelo a funções, bancos de dados e serviços externos. A aplicação é responsável por executar a função solicitada e retornar o resultado ao modelo.

Use a referência da Chat Completions API para consultar as definições dos parâmetros e os requisitos de compatibilidade dos modelos. O exemplo em Python abaixo usa uma solicitação de texto básica, sem ferramentas.

Os desenvolvedores podem acessar a Chat Completions API por meio de solicitações HTTP ou de um SDK oficial. O exemplo a seguir usa Python para enviar uma solicitação conversacional e recuperar a resposta gerada.

Etapa 1. Obtenha uma chave de API

Crie uma chave de API na plataforma OpenAI API e verifique se sua conta tem acesso ao modelo selecionado e créditos de API ou capacidade de faturamento suficientes. Armazene a chave em uma variável de ambiente, em vez de no código-fonte da aplicação. No macOS ou Linux, execute:

Substitua YOUR_API_KEY pela sua própria chave. No Windows, defina a mesma variável OPENAI_API_KEY no shell ou no ambiente do sistema.

Etapa 2. Instale o SDK Python da OpenAI

Instale a biblioteca oficial do Python usando pip:

Etapa 3. Inicialize o cliente da API

Importe o SDK e inicialize o cliente. OpenAI() lê automaticamente a variável de ambiente OPENAI_API_KEY definida na Etapa 1.

Etapa 4. Envie uma solicitação de conclusão de chat

Chame client.chat.completions.create() com um modelo e uma lista de mensagens. Este exemplo usa gpt-6-astra com baixo esforço de raciocínio e um limite total de geração de 4.096 tokens. Se esse modelo não estiver disponível para sua conta, escolha um modelo compatível com Chat Completions e ajuste os parâmetros de acordo com a documentação dele.

Neste exemplo:

• model identifica o modelo de linguagem usado para gerar a resposta.

• messages fornecem instruções e a entrada do usuário.

• reasoning_effort define o esforço de raciocínio para modelos compatíveis com esse parâmetro.

• max_completion_tokens limita os tokens gerados, incluindo os tokens de raciocínio. Ele não garante uma quantidade específica de texto visível.

• response.choices[0].message.content extrai a resposta do assistente.

Processe a resposta da API

Nesta solicitação sem streaming, a API retorna JSON contendo a conclusão e os metadados da solicitação. O SDK Python o analisa em um objeto ChatCompletion, por isso o exemplo acessa os campos por atributos como response.choices[0].message.content.

Os campos importantes da resposta incluem:

O campo finish_reason pode ajudar desenvolvedores a entender como uma geração foi encerrada. Valores comuns incluem stop, length e tool_calls.

Os desenvolvedores também podem inspecionar o campo usage para monitorar o consumo de token de entrada e saída, o que é útil para estimar os custos da API e otimizar o uso da aplicação.

Este exemplo mostra uma resposta de texto básica. Ao adicionar streaming, saída estruturada ou ferramentas, atualize tanto a lógica da solicitação quanto a de tratamento da resposta para corresponder ao modelo e ao endpoint selecionados.

Para desenvolvedores que buscam alternativas à API OpenAI Chat Completions, a Kimi API oferece acesso aos modelos de linguagem de grande porte da Moonshot AI em um formato de API compatível com OpenAI.

Kimi oferece as interfaces Chat Completions, Responses e Messages. O exemplo abaixo usa seu endpoint Chat Completions compatível com OpenAI para que você possa reutilizar o fluxo de trabalho do SDK apresentado acima. Configure uma chave da Kimi API, defina a URL base do Kimi e selecione um modelo compatível. Consulte a própria documentação do Kimi para parâmetros de modelo, funções das mensagens e suporte a ferramentas.

Etapa 1. Obtenha uma chave da Kimi API

Cadastre-se na plataforma da Kimi API e crie uma chave da API no console do desenvolvedor. Verifique seu saldo, acesso aos modelos e limites de taxa da conta antes de fazer sua primeira solicitação.

Armazene a chave do Kimi em uma variável de ambiente separada. No macOS ou Linux, execute:

Substitua YOUR_KIMI_API_KEY pela sua própria chave do Kimi. No Windows, defina a mesma variável KIMI_API_KEY em seu ambiente.

Etapa 2. Instale o SDK Python da OpenAI

Se o SDK ainda não estiver instalado, execute:

Etapa 3. Configure o cliente da Kimi API

Crie um kimi_client separado usando a URL base do Kimi e a variável KIMI_API_KEY definida na Etapa 1. Ler a chave com os.environ faz com que a ausência da variável de ambiente apareça imediatamente como um erro.

Etapa 4. Envie uma solicitação de Chat Completions

Use o mesmo método do SDK com o cliente Kimi. Esta solicitação seleciona kimi-k3, usa a função system compatível do Kimi para instruções e retorna uma resposta de texto sem streaming.

• Opções de modelo para diferentes cargas de trabalho: Kimi K3.1 Pro oferece suporte a raciocínio complexo, programação de longo prazo e trabalho de conhecimento. Sua variante Highspeed oferece resultados mais rápidos com os mesmos recursos do modelo. O exemplo acima usa Kimi K3; consulte a lista atual de modelos para informações sobre disponibilidade e migração.

• Compatibilidade com a API OpenAI: Desenvolvedores familiarizados com o formato OpenAI Chat Completions podem reutilizar uma estrutura de solicitação semelhante e fluxos de trabalho compatíveis do SDK ao integrar modelos Kimi.

• Conversas com múltiplos turnos: Desenvolvedores podem fornecer históricos de mensagens para permitir conversas sensíveis ao contexto, assistentes virtuais e aplicações interativas.

• Streaming e chamada de funções: A API oferece suporte a respostas em streaming e fluxos de trabalho de chamada de ferramentas, permitindo que desenvolvedores criem aplicações mais interativas e conectem modelos a funções externas.

• Entrada multimodal: Os modelos Kimi compatíveis podem processar diferentes tipos de entrada, incluindo texto, imagens e vídeo, dependendo dos recursos do modelo.

Ao trabalhar com a API Chat Completions, desenvolvedores podem encontrar erros relacionados à autenticação, à configuração da API, à disponibilidade do modelo ou aos limites de solicitação. Entender esses problemas comuns pode ajudar a identificar falhas e fazer a integração funcionar corretamente:

• Chave de API inválida ou ausente: Erros de autenticação, como HTTP 401, podem ocorrer quando a chave da API está incorreta, expirada, revogada ou não foi configurada adequadamente. Verifique se a chave é válida, se a variável de ambiente foi carregada corretamente e se a solicitação inclui as credenciais de autenticação apropriadas.

• URL base da API incorreta: Solicitações enviadas a um endpoint incorreto podem retornar erros como 404 ou falhas de conexão. Verifique se a URL base corresponde à documentação do provedor da API e se a solicitação usa o caminho de endpoint correto. Ao alternar entre a OpenAI e provedores compatíveis, lembre-se de atualizar a URL base adequadamente.

• ID de modelo inválido ou indisponível: Uma solicitação pode falhar se o nome do modelo especificado estiver incorreto, não estiver disponível para sua conta ou não for compatível com o endpoint selecionado. Consulte a documentação de modelos do provedor e confirme se o ID do modelo corresponde ao disponível para sua conta da API.

• Limite de contexto excedido: Se as mensagens de entrada combinadas e a saída gerada excederem a janela de contexto do modelo, a API poderá rejeitar a solicitação. Reduza o tamanho da entrada, remova o histórico de conversa desnecessário ou resuma mensagens anteriores antes de enviar a solicitação novamente.

• Saída truncada: Uma resposta pode ser interrompida antes de concluir o conteúdo solicitado se atingir o limite de max_completion_tokens. Aumente o limite de token quando houver suporte ou divida uma tarefa de geração longa em solicitações menores. Você também pode inspecionar choices[].finish_reason para verificar se a resposta terminou devido ao limite de length.

• Limite de taxa ou cota excedido: Para a OpenAI, HTTP 429 pode indicar um limite de taxa de solicitações ou de token, um limite de gastos ou outra restrição de uso. Inspecione o tipo e o código do erro antes de tentar novamente. Em caso de limite de taxa temporário, reduza a frequência das solicitações e siga Retry-After quando fornecido ou use espera exponencial.

Se o erro indicar créditos esgotados ou um limite de cobrança ou gastos, verifique o saldo e as configurações de cobrança da conta; tentativas repetidas não restaurarão o acesso. Ao usar Kimi ou outro provedor compatível, siga a documentação de códigos de erro desse provedor, pois os códigos de status e as regras de cota podem ser diferentes.

Para uma depuração mais eficiente, verifique o código de status HTTP e a mensagem de erro retornada pela API antes de alterar os parâmetros da solicitação. Esses detalhes podem ajudar a distinguir problemas de autenticação, erros de configuração e limites de uso.

A API Chat Completions pode atender a uma ampla variedade de cenários de aplicação. Seu formato estruturado de mensagens e os parâmetros de geração personalizáveis a tornam adequada tanto para recursos simples baseados em texto quanto para fluxos de trabalho de IA mais complexos.

• Chatbots de IA e assistentes virtuais: Desenvolvedores podem usar a API para criar assistentes de conversação para sites, aplicações móveis e plataformas de atendimento ao cliente. Ao enviar mensagens anteriores em solicitações subsequentes, as aplicações podem manter o contexto da conversa e fornecer respostas mais relevantes.

• Criação de conteúdo e edição de texto: A API pode gerar e transformar texto com base nas instruções do usuário. As aplicações podem usá-la para redigir posts de blog, escrever textos de marketing, resumir conteúdos longos, reescrever parágrafos e ajustar estilos de escrita para diferentes públicos e finalidades.

• Classificação de texto e extração de informações: Empresas podem integrar a API a fluxos de trabalho que processam grandes volumes de texto. Por exemplo, ela pode classificar feedback de clientes, identificar sentimentos, extrair informações importantes de mensagens e organizar conteúdo não estruturado em categorias predefinidas.

• Assistentes de programação: a API pode dar suporte a ferramentas de desenvolvimento de software gerando código, explicando conceitos de programação, sugerindo soluções e ajudando desenvolvedores a identificar erros. Os aplicativos também podem conectar o modelo a ferramentas externas de desenvolvimento por meio de chamadas de função.

• Fluxos de trabalho empresariais com IA: os desenvolvedores podem incorporar a API a aplicativos empresariais para automatizar tarefas repetitivas relacionadas à linguagem. Entre os exemplos estão o processamento de solicitações de clientes, a geração de relatórios, a extração de informações de documentos e a elaboração de respostas com base em instruções predefinidas.

A API de Chat Completions da OpenAI oferece aos desenvolvedores uma forma prática de levar a IA conversacional aos seus aplicativos e criar experiências de usuário mais úteis. Escolher o modelo certo, entender seus parâmetros e lidar cuidadosamente com as respostas da API pode fazer uma diferença real no desempenho de um aplicativo. No entanto, os desenvolvedores não precisam depender de um único provedor ao criar soluções com IA. Se quiser explorar outra opção, experimente a Kimi API e veja como sua configuração compatível com OpenAI se encaixa nas suas necessidades de desenvolvimento.