Autenticação, Chaves de API e Organização
Nesta página
Autenticação, Chaves de API e Organização
Antes de escrever uma única linha de código, tem de configurar o seu acesso à API. Esta lição abrange a criação de chaves, a estruturação do acesso através de organizações e projetos, e as precauções de segurança que previnem o pesadelo clássico: enviar acidentalmente uma chave para um repositório público, onde um estranho a consome durante a noite.
Criar a Sua Conta e Obter uma Chave
O processo consiste em três passos. Primeiro, aceda a platform.openai.com e crie uma conta; receberá automaticamente créditos gratuitos para começar a experimentar. De seguida, navegue até à secção API Keys do painel de controlo e gere uma nova chave. Só verá esta chave uma vez: copie-a imediatamente, mas não a cole no seu código.
# A sua chave de API tem este aspeto (nunca a partilhe!)
# sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Melhor prática: usar uma variável de ambiente
import os
api_key = os.environ.get("OPENAI_API_KEY")
O terceiro passo é declarar a variável de ambiente, o que depende da sua plataforma. Num computador de desenvolvimento, um ficheiro .env carregado pelo python-dotenv é frequentemente a opção mais conveniente. Num servidor, prefira uma variável de ambiente definida pelo seu orquestrador ou serviço de segredos.
# Linux / macOS — adicionar a ~/.bashrc ou ~/.zshrc
export OPENAI_API_KEY="sk-proj-your-key-here"
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-your-key-here"
# Ficheiro .env (com python-dotenv)
# .env
OPENAI_API_KEY=sk-proj-your-key-here
Que Tipo de Chave Escolher
As chaves de projeto, identificáveis pelo prefixo sk-proj-, estão vinculadas a um projeto específico e oferecem o melhor controlo. Utilizá-las-á em quase todos os casos. O SDK deteta-as automaticamente assim que a variável de ambiente está definida, razão pela qual OpenAI() é instanciado sem argumentos em todos os exemplos deste curso.
from openai import OpenAI
# O SDK deteta automaticamente a OPENAI_API_KEY
client = OpenAI()
# Ou especificar explicitamente (não recomendado para produção)
client = OpenAI(api_key="sk-proj-...")
As chaves de serviço são o segundo tipo. Concebidas para aplicações de servidor que requerem acesso elevado, concedem permissões adicionais e, por conseguinte, exigem cuidado extra: guarde-as num cofre de segredos e nunca distribua o seu valor para uma estação de trabalho de desenvolvimento.
Organizações e Projetos
O acesso está estruturado em três níveis aninhados:
- Organization: A sua empresa ou equipa
- Project: Um agrupamento lógico (ex.: “Chatbot de Produção”, “Análise de Dados”)
- API Key: Vinculada a um projeto específico
Se pertencer a várias organizações, especifique aquela que pretende utilizar ao instanciar o cliente:
from openai import OpenAI
# Especificar a organização (útil se pertencer a várias)
client = OpenAI(
organization="org-xxxxxxxxxxxx",
project="proj-xxxxxxxxxxxx"
)
Dedique algum tempo a dividir a sua utilização em projetos, em vez de encaminhar tudo através de uma única chave. Verá o benefício ao primeiro sinal de problemas. Cada projeto tem o seu próprio rastreio de utilização, permitindo-lhe atribuir custos a uma funcionalidade específica em vez de um total mensal opaco. Os limites de taxa também são separados: um trabalho em lote noturno que sature a sua quota não impedirá o seu chatbot de responder aos clientes. Pode então atribuir diferentes membros a cada projeto e, crucialmente, revogar uma chave comprometida sem interromper outras aplicações.
Nunca Exponha as Suas Chaves
A regra é simples e absoluta: uma chave nunca aparece no código fonte. O contraste entre os dois excertos abaixo fala mais alto do que uma longa palestra.
# MAU — chave codificada no código
client = OpenAI(api_key="sk-proj-abc123") # PERIGO!
# BOM — variável de ambiente
client = OpenAI() # Lê automaticamente a OPENAI_API_KEY
# BOM — ficheiro .env com python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()
O corolário diz respeito ao seu .gitignore, que deve excluir ficheiros de configuração locais antes do seu primeiro commit, e não depois. Uma chave que seja publicada e depois apagada permanece presente no histórico do repositório.
# ADICIONE SEMPRE estas linhas ao seu .gitignore
.env
.env.local
.env.production
*.key
Por fim, planeie uma rotação regular, a cada 90 dias. Pode fazê-lo sem tempo de inatividade: crie uma nova chave, atualize as suas implementações e, só depois, apague a antiga quando nada mais a estiver a utilizar.
Verificar a Sua Configuração
Antes de avançar, execute este script. Ele verifica a presença da chave, exibe uma versão truncada para confirmar que é a correta e, em seguida, faz uma chamada real. Volte a executar este teste sempre que um ambiente se comportar de forma estranha.
from openai import OpenAI
import os
def verify_configuration():
"""Verificar se a configuração da API está correta."""
# Verificar a chave
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
print("ERRO: OPENAI_API_KEY não definida")
return False
print(f"Chave detetada: {api_key[:8]}...{api_key[-4:]}")
# Testar a ligação
try:
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Reply only: OK"
)
print(f"Ligação bem-sucedida: {response.output_text}")
return True
except Exception as e:
print(f"ERRO de ligação: {e}")
return False
verify_configuration()
# Resultado esperado:
# Chave detetada: sk-proj-...xxxx
# Ligação bem-sucedida: OK
Pontos-chave
- Utilize chaves de projeto (
sk-proj-...) para cada aplicação - Guarde as suas chaves em variáveis de ambiente, nunca no código
- Organize o seu acesso com a hierarquia Organização → Projeto → Chave
- Efetue a rotação regular das suas chaves (a cada 90 dias)
- Adicione sempre
.envao seu.gitignore