Como Integrar a API da OpenAI no Seu App

Para integrar a API da OpenAI, crie uma chave de API em um projeto da OpenAI, guarde-a como segredo do servidor com o nome OPENAI_API_KEY e chame a API a partir de uma rota no seu próprio servidor, usando o SDK oficial da OpenAI — nunca a partir do código do navegador. A partir de setembro de 2026, o quickstart da OpenAI apresenta a Responses API como ponto de partida para projetos novos. Defina um limite de gasto antes do lançamento, limite o tamanho das respostas, restrinja com que frequência cada usuário pode chamar o recurso e trate os erros de limite de taxa com novas tentativas.

Este guia cobre a configuração, o fluxo de requisição, prompts para um construtor de IA e os erros que vazam chaves ou gastam dinheiro. Os detalhes da OpenAI vêm da documentação oficial de setembro de 2026. Para os conceitos gerais (tokens, janelas de contexto, preços), leia antes como usar APIs de LLM.

O que dá para construir com ela

Um assistente de chat dentro do seu app (como criar um app de chatbot com IA)
Botões de "Resumir isto", "Reescrever isto" ou "Rascunhar uma resposta"
Extração de dados estruturados de texto livre: transformar um e-mail em um pedido, classificar tickets de suporte
Busca e perguntas e respostas sobre o seu próprio conteúdo
Geração de imagens, áudio e outros recursos de mídia, dependendo dos modelos disponíveis

Mais ideias estão em como adicionar recursos de IA ao seu app.

Configurando sua conta na OpenAI

Crie uma conta e um projeto na plataforma da OpenAI. As melhores práticas de produção da OpenAI recomendam projetos separados para staging e produção, para que cada um tenha suas próprias chaves e limites.
Crie uma chave de API do projeto. A OpenAI recomenda definir uma data de expiração e rotacionar as chaves com regularidade.
Configure alertas de gasto e um limite rígido de gasto na página de limites. O guia da OpenAI diz que os alertas avisam quando o uso passa de um valor, e que o limite rígido impõe um teto mensal.
Adicione um método de pagamento. A documentação de limites de taxa da OpenAI descreve níveis de uso: seus limites aumentam automaticamente conforme você gasta mais com o tempo.

O fluxo da requisição

Navegador  ->  rota do seu servidor  ->  API da OpenAI
           <-  resposta (em streaming)  <-

O usuário clica em um botão ou envia uma mensagem.
O navegador chama a sua rota, por exemplo POST /api/summarise.
Seu servidor verifica se o usuário está logado e tem permissão para usar o recurso.
O servidor monta a requisição: instruções, a entrada do usuário e os dados do seu banco de dados que a tarefa precisar.
Ele chama a OpenAI com a chave do ambiente. Os SDKs da OpenAI leem OPENAI_API_KEY automaticamente.
Ele devolve a resposta em streaming ou de uma vez, e registra o uso de tokens.

Os pacotes SDK oficiais da OpenAI se chamam openai, tanto para JavaScript/TypeScript (npm) quanto para Python (pip).

Escolhendo um modelo

A OpenAI oferece vários modelos com preços e velocidades diferentes, e a linha de produtos muda com frequência. Comece com um modelo menor e mais barato, meça a qualidade com exemplos reais e suba de nível só se precisar. Mantenha o nome do modelo em um valor de configuração ou segredo, para trocá-lo sem reescrever o código. Consulte a página de preços da OpenAI para as tarifas atuais.

Opções e trade-offs

Decisão	Escolha simples	Quando ir além
Streaming	Devolver a resposta inteira	Use streaming em chats e respostas longas; o usuário vê o texto imediatamente
Memória da conversa	Enviar as mensagens recentes a cada vez	Resumir mensagens antigas quando os chats ficarem longos
Formato de saída	Texto simples	Pedir JSON estruturado quando o seu código precisar ler campos
Seus próprios dados	Incluir o registro relevante na requisição	Adicionar busca sobre o seu conteúdo quando houver material demais para incluir (veja o que é RAG)
Trabalho em massa, sem urgência	Fazer um laço sobre os itens	Usar a opção de lote da OpenAI, com custo menor, quando os resultados podem esperar

Prompts para dar ao seu construtor de IA

Uma primeira funcionalidade:

Adicione um botão "Resumir" na página do ticket. Ele chama uma rota no servidor POST /api/summarise que verifica se o usuário está logado, carrega o ticket e chama a Responses API da OpenAI com o SDK oficial openai e o segredo OPENAI_API_KEY. Leia o nome do modelo do segredo OPENAI_MODEL. Instruções: "Resuma em 3 tópicos e depois sugira uma resposta curta. Não invente números de pedido." Limite o tamanho da saída, transmita a resposta para a página em streaming e nunca envie a chave para o navegador.

Limites de segurança:

Limite cada usuário a 30 requisições de IA por hora, guardadas no banco de dados. Registre os tokens de entrada e saída de cada requisição com o ID do usuário e o nome do recurso. Se a OpenAI retornar 429, respeite o cabeçalho Retry-After e tente de novo com backoff exponencial e jitter, até 3 vezes; depois disso, mostre "A IA está ocupada, tente de novo em um minuto." Mostre um erro amigável para qualquer outra falha e mantenha o restante da página funcionando.

Tratando erros e limites

A OpenAI mede os limites de taxa de várias formas, incluindo requisições por minuto e tokens por minuto, e você atinge o que se esgotar primeiro. Quando ultrapassa um deles, a API retorna um 429 com um cabeçalho Retry-After. A documentação da OpenAI diz para tratar esse valor como um mínimo e acrescentar um pequeno atraso aleatório, para que os clientes não tentem todos ao mesmo tempo.

Também planeje para:

Timeouts em gerações longas. O streaming ajuda, assim como um limite sensato de saída.
Quedas do provedor. O recurso de IA deve falhar de forma elegante, sem quebrar a página.
Saída ruim. Valide a saída estruturada antes de salvá-la e não deixe a saída do modelo disparar ações sensíveis sem uma verificação no seu código.

Erros comuns

Chave no frontend ou no repositório. O código do navegador é público, e uma chave vazada pode ser abusada em minutos. Veja como manter as chaves de API seguras.
Sem limite de gasto. Um laço ou um usuário abusivo pode gerar uma conta grande rapidamente.
Sem limites por usuário. O limite do provedor protege a sua carteira, não os seus outros usuários.
Confiar no prompt para segurança. Usuários podem digitar "ignore as instruções anteriores". Permissões ficam no código do servidor.
Enviar mais do que o necessário. Documentos inteiros e históricos longos multiplicam o custo. Envie só o que a tarefa precisa.
Fixar o nome do modelo no código. Modelos são atualizados e descontinuados; transforme-o em uma configuração.
Enviar dados pessoais sem pensar. Leia os termos de uso de dados da OpenAI e envie apenas o necessário para o recurso.

Checklist

Projetos (ou chaves) da OpenAI separados para teste e produção
Chave guardada como segredo do servidor, nunca no código do navegador ou no repositório
Alertas de gasto e limite rígido de gasto configurados
Todas as chamadas passam pelo seu servidor e verificam as permissões do usuário
Tamanho da saída limitado; nome do modelo configurável
Limite de requisições por usuário no seu app
Tratamento de 429 com Retry-After, backoff e jitter
Estado de erro amigável; a página funciona sem a IA
Uso de tokens registrado por funcionalidade
Testado com entradas longas, vazias e hostis

Usando a API da OpenAI na Mythex

Recursos de IA em apps que você constrói na Mythex usam a sua própria chave da OpenAI e são cobrados na sua conta da OpenAI, e não nos créditos de build da Mythex. Adicione OPENAI_API_KEY como segredo do projeto pelo /secrets, pelas configurações do projeto ou pelo cartão de segredos que o agente mostra quando precisa de uma chave, e depois descreva o recurso com um prompt como os acima. Depois de mudar segredos em um app publicado, publique de novo para que ele use os novos valores. A receita da documentação Adicionar recursos de IA com suas próprias chaves de API tem um prompt inicial, e Segredos no chat explica o cartão de segredos. Comparando provedores? Veja como integrar a API do Claude.

Perguntas

Qual API da OpenAI devo usar em um app novo?

A partir de setembro de 2026, o quickstart da OpenAI apresenta a Responses API como ponto de partida para projetos novos, com exemplos usando client.responses.create() nos seus SDKs oficiais. Confira a documentação da OpenAI para a recomendação atual antes de começar.

Posso chamar a API da OpenAI a partir do navegador?

Não com a sua chave secreta. Qualquer pessoa pode ler o código do navegador e reutilizar a chave para aumentar a sua conta. O navegador deve chamar uma rota do seu próprio servidor, e o servidor chama a OpenAI com a chave guardada como variável de ambiente.

Como evito que a API da OpenAI custe caro demais?

A OpenAI recomenda, no seu guia de produção, configurar alertas de gasto e um limite mensal rígido na página de limites. No seu app, limite o tamanho das respostas, restrinja as requisições por usuário e registre o uso de tokens para ver quais funcionalidades custam mais.

O que significa um erro 429 da OpenAI?

Significa que você atingiu um limite de taxa. A documentação de limites da OpenAI diz que a resposta inclui o cabeçalho Retry-After; espere pelo menos esse tempo, acrescente um pequeno atraso aleatório e tente de novo com backoff exponencial.