Para usar a API do ChatGPT, o caminho mais direto é criar uma chave na plataforma da OpenAI, instalar o SDK oficial e fazer uma primeira chamada pela Responses API, que hoje é a base recomendada para apps conversacionais e agentes. A partir daí, o “segredo” vira engenharia de produto: definir instruções claras, controlar custo e latência, e tratar erros e segurança como parte do fluxo, não como remendo.
O que mudou na API e por que isso importa
A “API do ChatGPT” costuma ser usada como atalho para falar do uso dos modelos GPT via OpenAI API. Na prática, o que você integra no seu sistema é a plataforma de API, e o padrão mais novo para texto e agentes é a Responses API, que concentra recursos de conversação, ferramentas e fluxo stateful.
Uma regra simples evita retrabalho: se o seu projeto vai além de uma resposta única e precisa de contexto, ferramentas, ou evolução para um agente, comece com Responses. A migração pode ser incremental, e a própria documentação da OpenAI recomenda priorizar a Responses API como caminho padrão, inclusive porque ela absorveu melhorias inspiradas no Assistants API, que teve descontinuação anunciada em 26 de agosto de 2025 e data de encerramento em 26 de agosto de 2026.
| Decisão | Use quando | Por quê |
|---|---|---|
| Responses API | Chat com contexto, agentes, ferramentas, fluxo stateful | É o “bloco” mais completo e a direção recomendada |
| Chat Completions | Integração legada, fluxo simples já em produção | Continua suportado, mas tende a perder prioridade no roadmap |
Para acompanhar modelos disponíveis e escolher com base em custo e capacidade, vale manter o link oficial nos favoritos: lista de modelos na documentação.
Como gerar a chave e não se complicar
O acesso à API é baseado em chave. Essa chave identifica o seu projeto e define o que pode ser consumido, então ela deve ser tratada como credencial de produção, do mesmo jeito que token de banco ou provedor de pagamentos.
Checklist objetivo para não errar:
- Crie o projeto na plataforma e gere uma chave para ele, separando “dev” e “prod”.
- Guarde fora do código, usando variável de ambiente ou um cofre de segredos.
- Defina limites por projeto, com alertas de gasto e controle de uso.
O guia oficial de primeiros passos, com instruções de chave e exemplo funcional, está aqui: quickstart da OpenAI API.
Primeira requisição com Python do jeito certo
O jeito mais simples de testar é fazer uma chamada única, sem estado, e imprimir o texto final. O SDK oficial para Python instala com pip e lê a chave por variável de ambiente.
Instalação e variável de ambiente
pip install openai# macOS ou Linux
export OPENAI_API_KEY="sua_chave_aqui"
# Windows PowerShell
setx OPENAI_API_KEY "sua_chave_aqui"Exemplo mínimo com Responses API
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.4",
input="Escreva uma história de uma frase sobre um unicórnio."
)
print(response.output_text)Quando o seu caso é chat de várias voltas, a lógica de produto muda pouco: você passa um histórico estruturado, define instruções e, se fizer sentido, habilita ferramentas. A diferença é que o formato de entrada pode ser uma lista de itens, não só uma string.
Exemplo prático de chatbot simples para suporte
Cenário: um atendimento que responde dúvidas de entrega e troca, mas não pode inventar política. A decisão operacional é travar o comportamento na instrução e devolver respostas curtas, com pedido de confirmação quando faltar dado.
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
instructions = (
"Você é um atendente de e-commerce. "
"Responda em PT-BR, com objetividade. "
"Se faltar informação, faça uma pergunta curta. "
"Não invente prazos nem políticas."
)
resp = client.responses.create(
model="gpt-5.4",
instructions=instructions,
input=[
{"role": "user", "content": "Meu pedido 81233 ainda não chegou, o que faço?"}
]
)
print(resp.output_text)Como guiar o modelo sem “prompt mágico”
O que dá consistência não é um texto “criativo”, e sim estrutura. Pense em três camadas, como num briefing que qualquer time entende:
- Instruções: papel do assistente, limites, formato de resposta, tom.
- Dados: o que é fato do seu sistema, como status de pedido, catálogo, políticas.
- Pergunta do usuário: a mensagem em si, sem virar “comando” com privilégios.
Regra de decisão que evita prompt injection
Se o usuário puder inserir texto livre, trate esse texto como conteúdo, não como instrução. Na prática, isso significa separar a mensagem do usuário das regras do sistema, e recusar pedidos do tipo “ignore as regras anteriores” quando conflitam com as instruções.
Quando vale ativar ferramentas
Ferramentas fazem sentido quando a resposta depende de fonte externa, cálculo, arquivo, ou integração. Exemplos típicos:
- File search: responder com base em PDFs, políticas internas, manuais.
- Web search: fatos públicos que mudam todo dia.
- Function calling: chamar seu backend para buscar pedido, emitir boleto, abrir ticket.
Erros comuns e diagnóstico rápido
API em produção falha por motivos previsíveis. O objetivo é dar respostas úteis ao usuário final e registrar o que aconteceu para correção, sem vazar detalhes sensíveis.
1 Chave inválida ou ausente
Sintoma: erro de autenticação. Correção: conferir variável de ambiente, projeto correto e rotação de chaves em caso de vazamento.
2 Estouro de limite de uso ou taxa
Sintoma: respostas negadas por rate limit ou cota. Correção: implementar retry com backoff, cache de respostas para perguntas repetidas e, em tráfego alto, enfileirar requisições.
3 Contexto grande demais
Sintoma: a requisição fica pesada, cara, lenta, ou é rejeitada por limite. Correção: resumir histórico, manter só o que é relevante e mover conhecimento estável para busca em arquivos ou base de conhecimento.
4 Resposta incoerente ou “alucinação”
Sintoma: o modelo preenche lacunas com algo plausível, mas errado. Correção: exigir confirmação quando faltar dado, amarrar saídas com formatos claros e validar com seu sistema antes de executar ações.
Produção custos e governança em 3 regras
Em app real, o desafio é equilibrar qualidade, custo e latência. Um mini-modelo fácil de lembrar é o Triângulo QCL:
- Qualidade: modelos mais fortes e mais contexto tendem a melhorar resposta, mas custam mais.
- Custo: tokens e chamadas, especialmente com ferramentas, viram linha de despesa.
- Latência: respostas mais longas ou com raciocínio mais pesado demoram mais.
Regra 1 Escolha o menor modelo que passa no teste
Comece com um modelo custo-eficiente para a tarefa e suba apenas quando métricas de qualidade exigirem. A lista oficial de modelos ajuda a comparar opções: comparar modelos disponíveis.
Regra 2 Segurança não é filtro no final
Planeje moderação, revisão humana quando necessário e testes adversariais antes do lançamento. Para boas práticas e riscos comuns, a referência mais direta é a seção oficial de segurança: safety best practices.
Regra 3 Operação tem que ter painel e limite
Em produção, trate como qualquer serviço pago: defina limites por ambiente, monitore consumo e configure alertas. A documentação de melhores práticas de produção resume bem esse ponto: production best practices.
Com isso, a integração deixa de ser “colar um endpoint” e vira um sistema previsível: chave segura, modelo escolhido por métrica, prompts estruturados, observabilidade e fallback quando a API ou o contexto não ajudam.