Como Integrar a API da OpenAI na Sua App

Para integrar a API da OpenAI, crie uma chave de API num 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 de código do navegador. Em setembro de 2026, o guia de início rápido da OpenAI apresenta a Responses API como ponto de partida para projetos novos. Defina um limite de gastos antes do lançamento, limite o tamanho das respostas, restrinja a frequência com que cada utilizador pode usar a funcionalidade e trate os erros de limite de pedidos com novas tentativas.

Este guia cobre a configuração, o fluxo do pedido, prompts para um construtor de IA e os erros que expõem chaves ou desperdiçam dinheiro. Os detalhes da OpenAI são da sua documentação oficial em setembro de 2026. Para os conceitos gerais (tokens, janelas de contexto, preços), leia primeiro como usar APIs de LLM.

O que pode construir com ela

Um assistente de conversa dentro da sua app (como criar uma app de chatbot com IA)
Botões "Resumir isto", "reescrever isto" ou "redigir uma resposta"
Extração de dados estruturados a partir de texto livre: transformar um e-mail numa encomenda, classificar pedidos de suporte
Pesquisa e perguntas e respostas sobre os seus próprios conteúdos
Funcionalidades de imagem, voz e outros meios, consoante os modelos disponíveis

Há mais ideias em como adicionar funcionalidades de IA à sua app.

Configurar a sua conta OpenAI

Crie uma conta e um projeto na plataforma da OpenAI. As boas práticas de produção da OpenAI recomendam projetos separados para staging e produção, para que cada um tenha as suas próprias chaves e limites.
Crie uma chave de API do projeto. A OpenAI recomenda definir uma data de validade e rodar as chaves regularmente.
Defina alertas de gastos e um limite de gastos rígido na página de limites. O guia da OpenAI indica que os alertas o avisam quando o consumo ultrapassa um valor, e que um limite rígido impõe um teto mensal.
Adicione a faturação. A documentação de limites de pedidos da OpenAI descreve níveis de utilização: os seus limites sobem automaticamente à medida que gasta mais ao longo do tempo.

O fluxo do pedido

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

O utilizador clica num botão ou envia uma mensagem.
O navegador chama a sua rota, por exemplo POST /api/summarise.
O seu servidor verifica se o utilizador tem sessão iniciada e pode usar a funcionalidade.
O servidor constrói o pedido: instruções, o que o utilizador escreveu e os dados da base de dados de que a tarefa precisa.
Chama a OpenAI com a chave do ambiente. Os SDK da OpenAI leem OPENAI_API_KEY automaticamente.
Devolve ou envia a resposta em streaming, e regista o consumo de tokens.

O SDK oficial da OpenAI chama-se openai, tanto para JavaScript/TypeScript (npm) como para Python (pip).

Escolher um modelo

A OpenAI oferece vários modelos, a preços e velocidades diferentes, e a gama muda com frequência. Comece com um modelo mais pequeno e mais barato, meça a qualidade com exemplos reais e suba de modelo apenas se precisar. Guarde o nome do modelo num valor de configuração ou num segredo, para o poder trocar sem reescrever o código. Consulte a página de preços da OpenAI para as tarifas atuais.

Opções e compromissos

Decisão	Escolha simples	Quando ir mais longe
Streaming	Devolver a resposta completa	Use streaming no chat e em respostas longas; os utilizadores veem o texto de imediato
Memória da conversa	Enviar as mensagens recentes de cada vez	Resumir as mensagens antigas quando os chats se tornam longos
Formato de saída	Texto simples	Peça JSON estruturado quando o seu código precisa de ler campos
Os seus próprios dados	Incluir o registo relevante no pedido	Adicionar pesquisa sobre os seus conteúdos quando há demasiado para incluir (veja o que é RAG)
Trabalho em massa, sem urgência	Percorrer os itens em ciclo	Usar a opção de lotes da OpenAI para um custo mais baixo 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 pedido de suporte. Chama uma rota do servidor POST /api/summarise que verifica se o utilizador tem sessão iniciada, carrega o pedido de suporte 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 pontos e depois sugira uma resposta curta. Não invente números de encomenda." Limite o tamanho da resposta, envie-a em streaming para a página e nunca envie a chave ao navegador.

Proteções:

Limite cada utilizador a 30 pedidos de IA por hora, guardados na base de dados. Registe os tokens de entrada e de saída de cada pedido com o ID do utilizador e o nome da funcionalidade. Se a OpenAI devolver 429, respeite o cabeçalho Retry-After e tente novamente com recuo exponencial e variação aleatória até 3 vezes; depois disso, mostre "A IA está ocupada, tente novamente daqui a um minuto." Mostre uma mensagem amigável para qualquer outra falha e mantenha o resto da página a funcionar.

Tratar erros e limites

A OpenAI mede os limites de pedidos de várias formas, incluindo pedidos por minuto e tokens por minuto, e atinge-se primeiro o que se esgotar. Quando ultrapassa um deles, a API devolve um 429 com um cabeçalho Retry-After. A documentação da OpenAI indica que deve 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.

Prevja também:

Tempos limite em gerações longas. O streaming ajuda, tal como um limite razoável no tamanho da saída.
Interrupções do fornecedor. A funcionalidade de IA deve falhar com elegância sem partir a página.
Saídas incorretas. Valide a saída estruturada antes de a guardar, e não deixe que a saída do modelo dispare 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 divulgada pode ser abusada em minutos. Veja como manter as chaves de API seguras.
Sem limite de gastos. Um ciclo ou um utilizador abusivo pode aumentar muito a fatura depressa.
Sem limites por utilizador. O limite do fornecedor protege a sua carteira, não os outros utilizadores.
Confiar no prompt para a segurança. Os utilizadores podem escrever "ignore as instruções anteriores". As permissões pertencem ao código do servidor.
Enviar mais do que o necessário. Documentos inteiros e históricos longos multiplicam o custo. Envie apenas o que a tarefa precisa.
Fixar o nome do modelo no código. Os modelos são atualizados e descontinuados; torne-o uma definição.
Enviar dados pessoais sem pensar. Leia os termos de utilização de dados da OpenAI e envie apenas o que a funcionalidade precisa.

Lista de verificação

Projetos OpenAI separados (ou chaves separadas) para testes e produção
Chave guardada como segredo do servidor, nunca no código do navegador nem no repositório
Alertas de gastos e limite de gastos rígido definidos
Todas as chamadas passam pelo seu servidor e verificam as permissões do utilizador
Tamanho da resposta limitado; nome do modelo configurável
Limite de utilização por utilizador na sua app
Tratamento de 429 com Retry-After, recuo e variação aleatória
Estado de erro amigável; a página funciona sem a IA
Consumo de tokens registado por funcionalidade
Testado com entradas longas, vazias e hostis

Usar a API da OpenAI na Mythex

As funcionalidades de IA nas apps que constrói na Mythex usam a sua própria chave da OpenAI, faturada na sua conta OpenAI e não nos créditos de construção da Mythex. Adicione OPENAI_API_KEY como segredo do projeto através de /secrets, das definições do projeto ou do cartão de segredos que o agente mostra quando precisa de uma chave, e depois descreva a funcionalidade com um prompt como os acima. Depois de alterar segredos numa app publicada, publique novamente para que a app os use. A receita da documentação Adicionar funcionalidades de IA com as suas próprias chaves de API tem um prompt inicial, e Segredos no chat explica o cartão de segredos. A comparar fornecedores? Veja como integrar a API do Claude.

Perguntas

Qual API da OpenAI devo usar numa app nova?

Em setembro de 2026, o guia de início rápido da OpenAI apresenta a Responses API como ponto de partida para projetos novos, com exemplos que usam client.responses.create() nos seus SDK oficiais. Consulte 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 fatura. 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 demasiado?

O guia de boas práticas de produção da OpenAI recomenda alertas de gastos e um limite mensal rígido na página de limites. Na sua app, limite o tamanho das respostas, restrinja os pedidos por utilizador e registe o consumo de tokens para ver quais as funcionalidades mais caras.

O que significa um erro 429 da OpenAI?

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