API da OpenAI: Tutorial Completo

A API da OpenAI é a forma mais comum de integrar GPT-4 em suas aplicações. Este tutorial cobre tudo que você precisa saber para começar.

Setup Inicial

1. Criar Conta e API Key

1. Acesse platform.openai.com
2. Crie uma conta
3. Vá em API Keys → Create new secret key
4. Copie a key (só aparece uma vez!)
5. Adicione créditos (mínimo $5)

2. Configurar Ambiente

# Instalar SDK
pip install openai

# Configurar variável de ambiente
export OPENAI_API_KEY="sk-..."

# Ou em .env
OPENAI_API_KEY=sk-...

3. Primeira Chamada

from openai import OpenAI

client = OpenAI()  # Usa OPENAI_API_KEY automaticamente

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Olá! Como você está?"}
    ]
)

print(response.choices[0].message.content)
# "Olá! Estou bem, obrigado por perguntar..."

Chat Completions API

A API principal para conversas com GPT-4.

Estrutura de Mensagens

messages = [
    {
        "role": "system",
        "content": "Você é um assistente útil que responde em português."
    },
    {
        "role": "user",
        "content": "O que é Python?"
    },
    {
        "role": "assistant",
        "content": "Python é uma linguagem de programação..."
    },
    {
        "role": "user",
        "content": "Quais são suas principais aplicações?"
    }
]

# system: Define comportamento do assistente
# user: Mensagens do usuário
# assistant: Respostas anteriores do modelo

Parâmetros Importantes

response = client.chat.completions.create(
    model="gpt-4",                    # Modelo a usar
    messages=messages,                 # Histórico de conversa
    temperature=0.7,                   # Criatividade (0-2)
    max_tokens=500,                    # Limite de tokens na resposta
    top_p=1,                           # Nucleus sampling
    frequency_penalty=0,               # Penaliza repetição
    presence_penalty=0,                # Encoraja novos tópicos
    stop=["\n\n"],                   # Para de gerar nesses tokens
)

# temperature:
# 0 = determinístico, sempre mesma resposta
# 0.7 = balanceado (padrão)
# 1+ = mais criativo/aleatório

Acessando a Resposta

# Resposta completa
print(response)

# Texto da resposta
text = response.choices[0].message.content

# Tokens usados
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens

# Razão de parada
finish_reason = response.choices[0].finish_reason
# "stop" = completou normalmente
# "length" = atingiu max_tokens
# "tool_calls" = quer chamar função

Streaming

Receba a resposta palavra por palavra (melhor UX):

# Streaming básico
stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Conte uma história"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

# Em FastAPI
from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()

@app.get("/chat")
async def chat(message: str):
    async def generate():
        stream = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": message}],
            stream=True
        )
        for chunk in stream:
            if chunk.choices[0].delta.content:
                yield chunk.choices[0].delta.content
    
    return StreamingResponse(generate(), media_type="text/plain")

Function Calling (Tools)

Permite que o modelo chame funções definidas por você:

# 1. Definir ferramentas
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Busca previsão do tempo para uma cidade",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nome da cidade"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# 2. Chamar modelo com tools
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Como está o tempo em São Paulo?"}
    ],
    tools=tools,
    tool_choice="auto"  # ou "none" ou {"type": "function", "function": {"name": "get_weather"}}
)

# 3. Verificar se quer chamar função
message = response.choices[0].message
if message.tool_calls:
    for tool_call in message.tool_calls:
        function_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        
        # 4. Executar função
        if function_name == "get_weather":
            result = get_weather(arguments["city"])
        
        # 5. Retornar resultado para o modelo
        messages.append(message)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })
        
        # 6. Chamar modelo novamente
        final_response = client.chat.completions.create(
            model="gpt-4",
            messages=messages
        )

Embeddings

Converta texto em vetores numéricos para busca semântica:

# Gerar embedding
response = client.embeddings.create(
    model="text-embedding-ada-002",
    input="Como fazer um bolo de chocolate?"
)

embedding = response.data[0].embedding
# Lista com 1536 floats

# Busca por similaridade
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Comparar embeddings
query_embedding = get_embedding("receita de bolo")
doc_embedding = get_embedding("Bolo de chocolate: misture...")

similarity = cosine_similarity(query_embedding, doc_embedding)
# 0.92 = muito similar

Visão (GPT-4V)

Analisar imagens com GPT-4 Vision:

# Com URL
response = client.chat.completions.create(
    model="gpt-4-vision-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "O que tem nesta imagem?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }
    ]
)

# Com base64
import base64

with open("image.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gpt-4-vision-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Descreva esta imagem"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)

Boas Práticas para Produção

1. Tratamento de Erros

from openai import OpenAI, APIError, RateLimitError
import time

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4",
                messages=messages
            )
            return response
        
        except RateLimitError:
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
        
        except APIError as e:
            print(f"API error: {e}")
            raise
    
    raise Exception("Max retries exceeded")

2. Caching

import hashlib
import redis

cache = redis.Redis()

def get_cached_response(messages):
    # Criar key baseada nas mensagens
    key = hashlib.md5(str(messages).encode()).hexdigest()
    
    # Verificar cache
    cached = cache.get(key)
    if cached:
        return json.loads(cached)
    
    # Chamar API
    response = client.chat.completions.create(
        model="gpt-4",
        messages=messages
    )
    
    # Salvar no cache (1 hora)
    cache.setex(key, 3600, json.dumps(response.choices[0].message.content))
    
    return response.choices[0].message.content

3. Logging

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def call_llm(messages):
    logger.info(f"Calling GPT-4 with {len(messages)} messages")
    
    start = time.time()
    response = client.chat.completions.create(
        model="gpt-4",
        messages=messages
    )
    elapsed = time.time() - start
    
    logger.info(f"Response in {elapsed:.2f}s, tokens: {response.usage.total_tokens}")
    
    return response

4. Custos

# Monitorar custos
PRICES = {
    "gpt-4": {"input": 0.03, "output": 0.06},      # por 1k tokens
    "gpt-4o": {"input": 0.005, "output": 0.015},
    "gpt-3.5-turbo": {"input": 0.0005, "output": 0.0015},
}

def estimate_cost(response, model="gpt-4"):
    input_cost = (response.usage.prompt_tokens / 1000) * PRICES[model]["input"]
    output_cost = (response.usage.completion_tokens / 1000) * PRICES[model]["output"]
    return input_cost + output_cost

# Exemplo
response = call_llm(messages)
cost = estimate_cost(response)
print(f"Custo: $" + "{cost:.4f}")

Modelos Disponíveis