Chave API OpenAI: como criar, proteger e testar a sua

1. Entre na plataforma e escolha o projeto certo

Acesse platform.openai.com e crie uma conta ou faça login. Siga as etapas de configuração inicial que aparecerem. O guia de início rápido da OpenAI traz um link direto para o painel de chaves de API.

Pense na conta como seu crachá, na organização como a empresa e no projeto como uma sala reservada para um aplicativo. A chave é a credencial que seu software usa para entrar nessa sala.

No seletor de organizações, escolha a organização em que pretende trabalhar. Selecione um projeto existente ou, se você for proprietário da organização, use a opção Create project no menu de projetos e preencha os dados. Um nome como website-test deixa a finalidade mais clara. O guia de projetos da OpenAI explica esses controles.

Se o trabalho for para uma empresa, peça ao proprietário que adicione você ao projeto adequado. Evite iniciar a integração de um cliente em uma conta com cobrança pessoal só porque ela já está aberta.

2. Como criar sua chave API OpenAI no projeto

Nas configurações da organização, selecione o projeto, abra API Keys e clique em + Create new secret key. A chave criada ficará vinculada ao projeto selecionado. Instruções para criar chaves de projeto.

Para seu primeiro teste, use uma chave de projeto vinculada ao seu usuário. Se a plataforma pedir um nome, escolha algo fácil de reconhecer, como local-test. Selecione as permissões Restricted e habilite as operações de que o aplicativo precisa. All concede acesso completo e é a opção padrão; Read Only restringe a chave a operações de leitura. Permissões das chaves de API. Para o teste abaixo, permita a criação de Responses, operação que a OpenAI identifica pela permissão api.responses.write. Permissão de escrita de Responses.

Copie a chave imediatamente para um local seguro. A OpenAI só exibe o valor completo no momento da criação. Se você o perder, crie outra chave: não é possível visualizar a original novamente. Como encontrar e gerenciar chaves de API.

Defina uma data de expiração e registre quem ficará responsável pela substituição. A política da organização pode exigir um prazo de validade ou restringir os tipos de chave que você pode criar. Se alguma opção estiver indisponível, consulte o administrador sobre a política. Orientações da OpenAI para produção. Consulte o plano de expiração e rotação de chaves da API antes de transformar um teste em um serviço em operação.

Quando vale mais a pena usar uma conta de serviço?

Para um aplicativo em produção ou um fluxo de trabalho agendado da equipe, eu usaria uma conta de serviço: uma identidade para o software, em vez de uma identidade pessoal. Um proprietário da organização ou do projeto pode criá-la em Members → + Service account, dentro do projeto selecionado. Salve a chave gerada imediatamente. Use um projeto dedicado: contas de serviço não podem ser adicionadas diretamente ao projeto Default. Configuração de contas de serviço.

Depois de criar a conta, revise seu acesso nas configurações de API Keys do projeto. A janela de criação da conta de serviço não oferece os mesmos controles de permissão de uma chave vinculada a um usuário. Diferenças nas permissões. Na prática, isso mantém clara a responsabilidade pela credencial do aplicativo mesmo quando a composição da equipe muda.

3. Configure a cobrança da API e o limite de gastos

A cobrança do ChatGPT e a cobrança da API são separadas. Pagar pelo ChatGPT não configura o pagamento da API. Abra a visão geral de cobrança da API da organização correta; um proprietário da organização pode gerenciar essa cobrança. Orientações da OpenAI sobre cobrança.

Novas contas da API usam cobrança pré-paga. Selecione Add payment details, configure o pagamento, escolha a compra inicial de créditos e confirme. Confira a opção Use auto-reload antes de concluir: segundo a OpenAI, ela vem ativada por padrão. Desative-a se quiser fazer um teste com recargas manuais ou configure de forma consciente o saldo que dispara a recarga e o limite mensal de recargas. A compra pode levar alguns minutos para aparecer. Configuração do pré-pago.

Para consultar os preços atuais dos modelos, acesse a página de preços da OpenAI. O guia de preços da API da OpenAI deste site ajuda a relacionar esses valores ao orçamento do aplicativo.

Ative o bloqueio para interromper requisições ao atingir o limite

Em Project settings → Limits → Spend → Edit spend limit, informe o Monthly spend limit, ative Enforce a hard limit e salve. Você precisa ter permissão para gerenciar as configurações desse projeto. Crie um alerta de gastos abaixo do teto para que alguém possa agir antes da interrupção do serviço. Instruções para configurar o limite de gastos.

O bloqueio tem um atraso, por isso o gasto registrado pode ultrapassar um pouco o valor configurado. Um limite de gastos da organização abrange todos os seus projetos em conjunto. O consumo também pode superar o saldo pré-pago durante o atraso na interrupção, e as compras manuais ficam fora do limite de recargas automáticas. Funcionamento do limite com bloqueio, funcionamento do pré-pago.

Antes de colocar a integração em produção, leia o guia de limites de gastos com bloqueio da API da OpenAI e defina quem poderá elevar o teto se ele interromper o serviço.

4. Guarde a chave onde o aplicativo possa usá-la com segurança

Guarde a chave em um gerenciador de segredos, um sistema feito para armazenar credenciais, ou forneça-a ao servidor por uma variável de ambiente chamada OPENAI_API_KEY. Uma variável de ambiente é uma configuração com nome que o programa em execução consegue ler sem que o segredo esteja no código-fonte. Orientações de armazenamento em produção.

Não coloque uma chave secreta padrão da API no JavaScript de um site, em um aplicativo móvel, em um repositório, em uma captura de tela ou em uma mensagem ao suporte. O código do navegador e dos aplicativos móveis chega aos dispositivos dos usuários; a chave deve ficar no seu servidor, que deve fazer a requisição. Dê a cada integrante da equipe seu próprio acesso, em vez de compartilhar a chave de uma pessoa. Segurança das chaves de API.

Se uma ferramenta pedir que você cole uma chave: use apenas o campo de credenciais indicado na documentação, depois de decidir se confia no fornecedor para receber essa credencial. Minha recomendação é usar um projeto dedicado e uma chave com permissões restritas para a integração, com um teto de gastos e um responsável. Uma caixa de texto comum, uma mensagem de chat ou um “verificador de chaves” desconhecido não são lugares adequados para diagnosticar uma conexão. Pergunte ao fornecedor de quais permissões ele precisa e onde armazena a chave.

5. Teste com uma requisição curl

Execute os comandos abaixo no Bash do seu computador. curl é uma ferramenta de linha de comando que envia uma requisição web. As primeiras linhas pedem a chave sem exibi-la nem inserir seu valor literal no comando digitado; a variável de ambiente dura apenas durante essa sessão do shell.

read -r -s -p "OpenAI API key: " OPENAI_API_KEY
printf '\n'
export OPENAI_API_KEY

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Reply with a short greeting."
  }'

O teste usa a estrutura de requisição e o modelo do exemplo de geração de texto da OpenAI. A Responses API é o endpoint que recebe sua entrada e devolve a saída do modelo. O cabeçalho de autorização carrega a chave secreta; o corpo em JSON escolhe o modelo e fornece a instrução. Essa requisição usa a API, portanto a cobrança e o acesso ao modelo precisam estar configurados.

Uma resposta bem-sucedida contém um array output com uma mensagem que inclui conteúdo output_text. Procure a saudação ali. Não presuma que o texto estará sempre no primeiro item do array. Se receber um objeto error, use a mensagem e o código para consultar as orientações abaixo. Estrutura da resposta.

Depois do teste, execute unset OPENAI_API_KEY para limpar a variável desse shell quando não precisar mais dela. Para colocar o aplicativo em produção, configure a chave no ambiente de hospedagem, em vez de repetir a solicitação no terminal.

A chave não funciona? Confira estes pontos primeiro

Leia o erro antes de criar outra chave. Várias falhas não têm relação com a credencial em si.

Uma resposta 429 pode indicar um problema de gastos ou de créditos, além de um limite de requisições. Repetir tentativas não repõe créditos nem altera um teto configurado. Códigos de erro da OpenAI, permissões das chaves.

Sua chave de API vazou? Revogue-a imediatamente

Considere exposta qualquer chave secreta colada em um repositório público, uma captura de tela ou uma mensagem. Apagar a cópia visível não invalida as cópias que alguém já possa ter obtido.

1. Revogue a chave exposta. Abra a página de chaves de API no projeto correto e exclua a chave. Os aplicativos que a utilizam podem parar até que você a substitua. Exclusão de chaves.
2. Crie uma substituta e atualize os aplicativos afetados. Teste a nova chave e confira se os processos em produção estão usando essa credencial.
3. Revise o uso e a cobrança. Investigue requisições inesperadas e entre em contato com o suporte da OpenAI se suspeitar de uso indevido. A OpenAI recomenda a rotação imediata quando há suspeita de vazamento. Orientações para responder a vazamentos.
4. Corrija a exposição. Remova a chave do código e dos logs e corrija a prática de armazenamento ou compartilhamento que causou o vazamento. Se a própria conta puder ter sido comprometida, altere a senha, encerre as outras sessões e denuncie atividades não autorizadas. Etapas para recuperar a conta.

Cinco situações em que essa configuração faz diferença

O benefício é ter uma integração com responsável e orçamento definidos. Estas são formas práticas de uma equipe aplicar a configuração, em ordem de utilidade imediata.

Uma chave funcionando comprova que uma requisição pode ser executada. Ela não comprova que seus prompts são confiáveis, que um fornecedor cuida bem das credenciais ou que uma automação deve ter acesso aos dados dos clientes. Essas continuam sendo decisões de produto e de operação.

Duas soluções úteis que podem nascer dessa configuração

A oportunidade mais forte é um assistente de conexão integrado a softwares que pedem uma chave da OpenAI aos clientes. A DataForSEO estima 1,000 buscas mensais nos Estados Unidos por “how to get openai api key”. Isso aponta uma dificuldade na configuração, não uma previsão de clientes pagantes. Um fornecedor de software poderia comprar ou desenvolver um checklist guiado para o projeto, um campo seguro de credenciais, um botão de teste explícito e um resultado fácil de entender. A versão mínima deve ficar dentro do produto que precisa da conexão. O desafio: os próprios fornecedores podem desenvolver isso, então o valor precisa vir da redução da demanda de suporte e da manutenção de instruções atualizadas.

Um explicador de erros é um recurso útil para o suporte, mas tem demanda menor como produto independente. A mesma consulta estima apenas 10 buscas mensais nos Estados Unidos por “openai api key not working”. Um fornecedor de automação ou uma agência de implementação poderia oferecer um formulário que recebe o código e a mensagem de erro com os dados sensíveis removidos e explica se é preciso corrigir as credenciais, os créditos, as permissões ou o ritmo das requisições. A primeira versão precisa de uma tabela de decisão mantida em dia, sem guardar a chave do usuário. O desafio está no baixo volume de buscas medido e no fato de muitas ferramentas já exibirem esses erros. Eu incluiria esse recurso na configuração inicial, em vez de lançar um produto pago separado.

Esses números são estimativas da visão geral de palavras-chave da DataForSEO para buscas em inglês nos Estados Unidos, consultadas para este guia. Eles medem buscas, não usuários únicos nem intenção de compra.

Para colocar em prática na segunda-feira: escolha uma integração, defina seu responsável, crie o projeto, configure o controle de gastos e salve o resultado de um teste bem-sucedido com a chave removida. Isso deixa um registro útil para quem assumir a manutenção depois.

Se você quer ajuda para levar essa integração à produção, a página de sistemas de IA em produção aborda o trabalho operacional envolvido.