Como Usar a API da OpenAI: Guia Para Iniciantes em Python

Você quer integrar o ChatGPT no seu projeto, mas não sabe por onde começar? Este guia cobre tudo que você precisa — da criação da conta até seu primeiro chatbot funcional — sem assumir experiência prévia com APIs.

---

O Que é a API da OpenAI?

A API da OpenAI é o que permite que desenvolvedores usem os modelos GPT (ChatGPT, DALL-E, Whisper) diretamente no código, sem depender da interface web. Com ela você pode:

Criar chatbots personalizados para seu produto
Automatizar geração de texto (e-mails, posts, resumos)
Construir assistentes que entendem contexto
Analisar sentimentos, classificar textos
Gerar imagens programaticamente com DALL-E

---

Passo 1: Criar Conta e Obter a Chave

1. Acesse platform.openai.com

2. Crie conta com e-mail (confirme via link)

3. Acesse API Keys no menu lateral

4. Clique em "Create new secret key"

5. Dê um nome e copie a chave imediatamente (não aparece novamente)

Importante: Adicione créditos em Billing. A API não tem plano gratuito — mas custa muito pouco para começar (R$20 sustentam semanas de testes).

---

Passo 2: Instalar o SDK Python

# Criar ambiente virtual (recomendado)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Instalar pacotes necessários
pip install openai python-dotenv

---

Passo 3: Configurar Credenciais com Segurança

Nunca coloque a chave diretamente no código. Use variáveis de ambiente:

# Criar arquivo .env na raiz do projeto
OPENAI_API_KEY=sk-proj-...

# Adicionar ao .gitignore
echo ".env" >> .gitignore

---

Passo 4: Primeira Chamada à API

# hello_gpt.py
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()  # carrega variáveis do .env

client = OpenAI()  # lê OPENAI_API_KEY automaticamente

response = client.chat.completions.create(
    model="gpt-4o-mini",       # modelo mais barato para começar
    messages=[
        {
            "role": "user",
            "content": "Explique o que é machine learning em 2 frases simples."
        }
    ],
    max_tokens=200,            # limite de tokens na resposta
    temperature=0.7            # criatividade: 0 = determinístico, 2 = muito criativo
)

# Extrair o texto da resposta
texto = response.choices[0].message.content
print(texto)

Execute:

python hello_gpt.py

---

Entendendo os Parâmetros Principais

model — Qual GPT usar

|---|---|---|---|

Regra de ouro: Comece com gpt-4o-mini. Só suba para modelos mais caros se a qualidade não for suficiente.

temperature — Criatividade

# 0: Sempre a mesma resposta, muito previsível
# Ideal para: classificação, extração de dados, perguntas factuais
temperature=0

# 0.7: Equilibrio (padrão recomendado)
# Ideal para: assistentes, chatbots, textos gerais
temperature=0.7

# 1.5-2: Muito criativo, pode ser incoerente
# Ideal para: brainstorming, poesia, ficção criativa
temperature=1.5

max_tokens — Limite de resposta

max_tokens=100    # resposta curta (resumo, classificação)
max_tokens=1000   # resposta média (parágrafo ou dois)
max_tokens=4096   # resposta longa (artigo, análise extensa)

---

Criando um Chatbot com Histórico

Um chatbot precisa lembrar da conversa anterior. Faça isso incluindo o histórico no array de mensagens:

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI()

def chatbot_simples():
    print("Chatbot iniciado! Digite 'sair' para encerrar.\n")
    
    historico = [
        {
            "role": "system",
            "content": "Você é um assistente prestativo que responde sempre em português do Brasil. Seja conciso e direto."
        }
    ]
    
    while True:
        usuario = input("Você: ").strip()
        
        if usuario.lower() in ["sair", "exit", "quit"]:
            print("Até logo!")
            break
        
        if not usuario:
            continue
        
        # Adicionar mensagem do usuário ao histórico
        historico.append({"role": "user", "content": usuario})
        
        # Chamar a API com o histórico completo
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=historico,
            max_tokens=500,
            temperature=0.7
        )
        
        # Extrair resposta
        resposta = response.choices[0].message.content
        
        # Adicionar resposta da IA ao histórico
        historico.append({"role": "assistant", "content": resposta})
        
        print(f"Assistente: {resposta}\n")

if __name__ == "__main__":
    chatbot_simples()

---

Roles nas Mensagens

O array messages aceita 3 tipos de role:

messages = [
    # system: Define o comportamento do assistente
    {
        "role": "system",
        "content": "Você é um especialista em culinária brasileira. Responda apenas sobre comida."
    },
    # user: Mensagem do usuário
    {
        "role": "user",
        "content": "Como fazer brigadeiro?"
    },
    # assistant: Resposta anterior da IA (para multi-turn)
    {
        "role": "assistant",
        "content": "Para fazer brigadeiro, você vai precisar de..."
    },
    # Próxima mensagem do usuário
    {
        "role": "user",
        "content": "E o tempo de cozimento?"
    }
]

---

Analisando o Custo da Chamada

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Olá"}],
)

# Ver tokens usados
print(f"Tokens de entrada: {response.usage.prompt_tokens}")
print(f"Tokens de saída: {response.usage.completion_tokens}")
print(f"Total de tokens: {response.usage.total_tokens}")

# Calcular custo (gpt-4o-mini)
custo_entrada = response.usage.prompt_tokens * 0.15 / 1_000_000
custo_saida = response.usage.completion_tokens * 0.60 / 1_000_000
custo_total = custo_entrada + custo_saida

print(f"Custo desta chamada: ${custo_total:.8f} USD")

---

Tratamento de Erros

from openai import OpenAI, AuthenticationError, RateLimitError, BadRequestError

client = OpenAI()

def chamar_gpt_seguro(mensagem: str) -> str:
    try:
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": mensagem}],
            max_tokens=500
        )
        return response.choices[0].message.content
        
    except AuthenticationError:
        return "Erro: Chave de API inválida. Verifique seu OPENAI_API_KEY."
        
    except RateLimitError:
        return "Erro: Limite de requisições atingido. Aguarde um momento."
        
    except BadRequestError as e:
        return f"Erro no conteúdo da mensagem: {str(e)}"

---

Próximos Passos

Depois de dominar o básico, explore:

1. Streaming: Mostrar resposta enquanto é gerada (como o ChatGPT faz)

2. Function Calling: Fazer o modelo chamar funções do seu código

3. Embeddings: Transformar texto em vetores para busca semântica

4. Fine-tuning: Treinar o modelo com seus próprios dados

5. Assistants API: Criar assistentes com arquivos e ferramentas persistentes

---

Perguntas Frequentes

Preciso de cartão de crédito para usar a API?

Sim, a API da OpenAI não tem plano gratuito (apenas $5 de crédito inicial para novos usuários). Depois é necessário adicionar crédito via cartão.

Quanto custa para fazer 1.000 chamadas?

Com gpt-4o-mini e respostas de 200 tokens cada: aproximadamente $0,15 USD — menos de R$1.

A API é a mesma coisa que o ChatGPT?

Mesmos modelos, mas sem memória persistente entre sessões. Você gerencia o histórico manualmente — o que dá muito mais controle.

Posso usar a API em produção para meu app?

Sim. Adicione limites de uso por usuário, monitore custos, implemente cache para perguntas repetidas, e use rate limiting para evitar gastos inesperados.

Como usar a API da OpenAI em Python: Tutorial para Iniciantes