Integrar a OpenAI API exige apenas quatro coisas: uma conta com a qual seja possível entrar, uma API Key utilizável, um projeto com cobrança habilitada e uma Base URL correta, além de uma primeira chamada bem-sucedida. Parece simples, mas o que costuma travar as equipes novas não é o código, e sim o sistema de contas, os meios de pagamento e a montagem do endereço.

Este artigo segue a ordem real de operação: conta e projeto, criação da Key, recarga, instalação do SDK, primeira chamada com a Responses API, consulta de uso, diagnóstico de erros 401 e 429 e, por fim, como trocar a Base URL para um gateway compatível com OpenAI. Os exemplos usam principalmente a Responses API; ferramentas antigas que só aceitam Chat Completions podem substituir a interface seguindo a mesma lógica.

Nota: OpenAI, ChatGPT e GPT são marcas da OpenAI. Este artigo toma como exemplo o comportamento público das interfaces em outubro de 2026; nomes de modelos, cotas e preços seguem a página de preços e a documentação oficial.

1. O que são conta, organização e projeto

A plataforma da OpenAI tem pelo menos três camadas, e misturá-las é a fonte mais comum de erros:

  • Conta: a credencial de acesso, que define quem pode entrar no console;
  • Organização: a unidade à qual pertencem a cobrança e o uso; a colaboração em equipe costuma ser administrada por organização;
  • Projeto: a unidade de isolamento de Keys, uso e permissões; recomenda-se separar por ambiente ou por linha de negócio.

Um erro comum é confundir a assinatura do ChatGPT com o saldo da API. São coisas distintas: a assinatura dá acesso ao produto de chat, e a API é cobrada separadamente conforme o consumo real. Antes de integrar, a equipe deve definir quem administra a conta, quem paga e quem tem permissão de administrador, para que a titularidade das Keys não se perca quando as pessoas mudarem.

2. Ordem para criar uma API Key

Siga os passos abaixo sem pular etapas:

  1. Entre no console da API com uma conta de administrador e confirme se está na organização correta.
  2. Crie ou selecione um projeto dentro da organização, separando "desenvolvimento / testes / produção".
  3. Acesse a página API Keys do projeto e crie uma chave nova.
  4. Dê à Key um nome que indique o uso, por exemplo "produção-atendimento".
  5. Copie a Key completa imediatamente e guarde-a em um gerenciador de senhas ou no gerenciador de segredos da plataforma de implantação.
  6. Configure permissões, orçamento ou limite de cota do projeto conforme necessário e salve.

A Key completa costuma aparecer apenas uma vez, no momento da criação. É normal que a página depois mostre só os primeiros e os últimos caracteres; não conte com copiá-la mais tarde. Se ela for perdida, crie uma nova Key e desative a antiga em vez de tentar recuperá-la.

3. Recarga, faturamento e cotas

Se a API é pré-paga ou pós-paga depende do tipo de conta e da região, e o console é a referência. Antes de ativar, verifique três pontos:

  1. Se o meio de pagamento aceita seu cartão ou canal;
  2. Como funcionam o ciclo de faturamento e a obtenção de notas fiscais;
  3. Se é possível definir alertas de orçamento e limites rígidos por projeto.

Falhas de pagamento são um problema frequente na fase de integração. Quando o cartão é recusado, confira primeiro o endereço de cobrança, o nome do titular e o método de verificação, e depois contate o emissor; não envie várias tentativas em pouco tempo, pois alguns sistemas antifraude bloqueiam a conta por isso. Equipes que usam um gateway normalmente podem recarregar em yuan; taxas e regras de crédito seguem a página de preços, que pode ser atualizada — vale o valor exibido no momento do pedido.

4. Instalar o SDK e fazer a primeira chamada com curl

Instale primeiro o SDK oficial de Python:

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-sua-chave"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="nome-do-modelo-copiado-da-pagina-de-precos"

Chame a Responses API com curl para confirmar endereço, Key e rede:

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "Explique em uma frase o que é um gateway de API."
  }'

Não escreva o nome do modelo de memória: copie da página de preços ou da documentação oficial o nome disponível no momento e guarde-o na variável OPENAI_MODEL. Um retorno 200 com conteúdo no corpo indica que o caminho está funcionando; um 401 aponta primeiro para a Key, e um 404 para a Base URL e o nome do modelo.

5. Primeira chamada em Python

O exemplo abaixo envia uma requisição mínima à Responses API e imprime o texto:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="Explique em três frases os limites das suas capacidades.",
)

print(resp.output_text)

Se seu framework só aceita Chat Completions, troque a chamada por client.chat.completions.create(...) e coloque as mensagens em messages. As duas interfaces usam caminhos diferentes, e misturá-las é a causa mais comum de erros 404.

6. Entender uso e faturamento

A página Usage do console costuma mostrar o consumo por projeto, modelo e período, separando entrada e saída. No início, vale consultar uma vez por dia e confirmar:

  • qual projeto está consumindo;
  • quanto cabe à entrada e quanto à saída;
  • se há tentativas repetidas por falha fora do normal;
  • se os alertas de orçamento estão funcionando.

O request ID devolvido nas chamadas deve ser mantido nos logs. Em disputas de cobrança ou incidentes, ele é o primeiro material que o provedor usa para localizar o problema. A equipe também deve registrar no aplicativo a relação entre usuário, módulo funcional e request ID; caso contrário, a fatura mostra apenas o total e não permite atribuição.

7. Como diagnosticar 401 e 429

O 401 indica que a identidade não foi reconhecida. Verifique na ordem: se o cabeçalho inclui Bearer; se a Key tem espaço ou quebra de linha extra; se a Key foi excluída ou o projeto está desativado; e se uma Key de gateway foi enviada ao endereço oficial. Antes de trocar a Key, confirme para onde a requisição está realmente indo, ou o esforço pode ser em vão.

O 429 tem dois significados: limite de requisições e saldo insuficiente. Leia o código de erro e os cabeçalhos da resposta em vez de reduzir a velocidade por padrão. insufficient_quota normalmente indica saldo ou cota esgotados e exige recarga ou ajuste do limite do projeto; apenas erros de taxa justificam recuo exponencial. Repetir só faz sentido para 429, 5xx e erros de rede; repetir 400, 401, 403 ou 404 apenas desperdiça cota. A ordem completa de diagnóstico está na página de preços e na documentação do provedor.

8. Conexão direta ou gateway compatível

Dimensão Conexão direta oficial Gateway compatível com OpenAI
Endereço https://api.openai.com/v1 Base URL fornecida pelo gateway, geralmente também terminada em /v1
Conta e pagamento Conta oficial, com os meios aceitos oficialmente Cadastro no site, com recarga em yuan e nota fiscal
Rede Depende da rede local e do link internacional Costuma oferecer entrada acessível no país
Escopo de modelos Modelos próprios da OpenAI Pode reunir modelos de vários fornecedores, conforme a página de preços
Cobrança Fatura oficial Saldo e registro de uso no site
Incidentes Canais de suporte oficiais O gateway investiga o upstream; o usuário mantém o request ID
Cenário indicado Uso exclusivo da OpenAI com pagamento e conformidade já resolvidos Equipes locais, vários modelos e fatura unificada

Não escolha apenas pelo preço unitário. A fluidez do pagamento, quem resolve incidentes e a possibilidade de trocar de modelo a qualquer momento afetam o custo de longo prazo. Os preços mudam; use sempre a página de preços.

9. Trocar para um gateway compatível: só a Base URL

A migração costuma custar menos do que parece, porque o gateway compatível mantém o mesmo formato de requisição. A ordem é:

  1. Cadastre-se no gateway e crie uma Key na página de cadastro.
  2. Troque OPENAI_BASE_URL pelo endereço do gateway, mantendo /v1.
  3. Substitua a Key pela do gateway; não misture as duas.
  4. Copie o nome do modelo da página de preços do gateway em vez de tentar a sorte com o nome oficial.
  5. Chame primeiro /v1/models e uma requisição mínima; só depois migre o tráfego de produção.
  6. Mantenha a rota oficial ou uma rota de reserva como plano de degradação.

"Compatível com OpenAI" significa compatibilidade de formato de requisição e resposta, não que todas as capacidades estendidas sejam idênticas. Arquivos, processamento em lote, chamadas de ferramentas e outras interfaces avançadas devem ser verificados item por item na documentação do gateway; não presuma que tudo está disponível. Os detalhes do escopo de compatibilidade estão na página de preços.

10. Segurança da Key e checklist antes de ir ao ar

O vazamento de uma Key gera custos imediatos. Requisitos mínimos:

  • Manter a Key apenas em variáveis de ambiente do servidor ou em um serviço de gestão de segredos, nunca no código de front-end nem no Git;
  • Separar Keys por ambiente, sem compartilhar entre teste e produção;
  • Identificar responsável e finalidade de cada Key e desativá-la quando alguém sair ou o projeto terminar;
  • Não imprimir a Key completa nos logs, apenas os quatro últimos caracteres;
  • Fazer rotação periódica e revogar imediatamente ao detectar chamadas anômalas.

Antes de entrar em produção, confirme item por item:

  • [ ] Conta, organização e projeto estão claramente atribuídos;
  • [ ] O meio de pagamento funciona e os alertas de orçamento estão configurados;
  • [ ] A Key está em variável de ambiente ou gestor de segredos;
  • [ ] A Base URL tem apenas um /v1;
  • [ ] A requisição mínima retorna 200 com conteúdo normal;
  • [ ] O recuo para 429 e a repetição para 5xx estão configurados;
  • [ ] Os logs de uso incluem request ID, modelo e latência;
  • [ ] A rota de reserva e o processo de desativação de Keys foram testados.

11. Perguntas frequentes

API Key e assinatura do ChatGPT são a mesma coisa?

Não. A assinatura e a API são cobradas separadamente, e a API Key é criada e administrada apenas na plataforma de API. Na prestação de contas, a equipe deve separar as duas despesas.

Por que não vejo a Key completa depois de criá-la?

A chave completa geralmente é exibida uma única vez, na criação; a plataforma mantém apenas parte dos caracteres para identificação. Se ela for perdida, crie uma nova e desative a antiga.

Onde a Base URL deve ser preenchida?

Até o domínio mais /v1, sem /chat/completions nem /responses. O caminho é montado pelo SDK ou pela própria requisição; um trecho extra causa 404.

Uma Key pode servir a vários projetos?

Tecnicamente sim, mas não é recomendável na gestão. Separar Keys por projeto ou ambiente permite controlar permissões, atribuir uso e reduzir o impacto de um vazamento.

Equipes locais precisam obrigatoriamente de um gateway?

Não necessariamente. Depende do canal de pagamento, da qualidade da rede, dos requisitos de conformidade e da necessidade de vários modelos. Quem usa apenas a OpenAI e já tem pagamento e rede estáveis pode conectar direto; quem precisa de liquidação em yuan e entrada unificada pode avaliar a migração com base na página de preços.

Próximo passo

Primeiro faça a requisição mínima funcionar; depois conecte o negócio. Se precisar de recarga em yuan e uma entrada unificada para vários modelos, comece pelo cadastro no ZSQH AI Gateway; modelos e preços seguem a página de preços.

Leituras relacionadas: