Tutorial da API OpenAI em Python

Este tutorial aborda o uso da API OpenAI com Python, desde a instalação até casos de uso avançados. Todos os exemplos funcionam com o APIMaster.ai — basta alterar a api_key e a base_url.

Instalação

pip install openai

Requer Python 3.8+. O pacote openai é o SDK oficial da OpenAI (versão 1.x).

Configuração Inicial

from openai import OpenAI

client = OpenAI(
    api_key="SUA_CHAVE_APIMASTER",
    base_url="https://apimaster.ai/v1",
)

Ou use variáveis de ambiente (recomendado):

export OPENAI_API_KEY="SUA_CHAVE_APIMASTER"
export OPENAI_BASE_URL="https://apimaster.ai/v1"

from openai import OpenAI
client = OpenAI()  # lê as variáveis de ambiente automaticamente

Completations Básicas de Chat

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "Você é um expert em Python."},
        {"role": "user", "content": "O que é um generator em Python?"},
    ],
)

print(response.choices[0].message.content)
print(f"Tokens usados: {response.usage.total_tokens}")

Respostas em Streaming

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Escreva uma busca binária em Python."}],
    stream=True,
)

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

Conversas com Múltiplas Interações

messages = [
    {"role": "system", "content": "Você é um assistente útil de programação."}
]

def send(user_text):
    messages.append({"role": "user", "content": user_text})
    resp = client.chat.completions.create(model="gpt-5.4", messages=messages)
    reply = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": reply})
    return reply

print(send("Explique list comprehensions."))
print(send("Dê-me um exemplo mais difícil."))

Saída Estruturada (Modo JSON)

Force o modelo a retornar JSON válido:

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {
            "role": "user",
            "content": "Extraia o nome, email e empresa de: 'Contacte Jane Smith (jane@acme.com) na Acme Corp.'",
        }
    ],
    response_format={"type": "json_object"},
)

data = json.loads(response.choices[0].message.content)
print(data)  # {"nome": "Jane Smith", "email": "jane@acme.com", "empresa": "Acme Corp"}

Chamada de Funções (Uso de Ferramentas)

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Obter o preço atual da ação para um símbolo ticker",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {"type": "string", "description": "Ticker da ação, ex. AAPL"},
                },
                "required": ["ticker"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Qual é o preço atual da ação da Apple?"}]

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

# Processar chamada de ferramenta
if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"Chamando {tool_call.function.name} com {args}")
    
    # Simular resultado da função
    result = {"ticker": args["ticker"], "price": 189.50}
    
    # Enviar resultado de volta
    messages.append(response.choices[0].message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })
    
    final = client.chat.completions.create(model="gpt-5.4", messages=messages)
    print(final.choices[0].message.content)

Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Tutorial da API OpenAI em Python", "Fundamentos de machine learning"],
)

embeddings = [item.embedding for item in response.data]
print(f"Dimensões do embedding: {len(embeddings[0])}")

Uso Assíncrono

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="SUA_CHAVE_APIMASTER",
    base_url="https://apimaster.ai/v1",
)

async def generate(prompt: str) -> str:
    resp = await client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content

async def main():
    # Executar 5 requisições concorrentemente
    prompts = [f"Explique o conceito #{i}" for i in range(5)]
    results = await asyncio.gather(*[generate(p) for p in prompts])
    for r in results:
        print(r[:100])

asyncio.run(main())

Tratamento de Erros

from openai import OpenAI, AuthenticationError, RateLimitError, APIError
import time

def safe_call(client, **kwargs):
    for tentativa in range(3):
        try:
            return client.chat.completions.create(**kwargs)
        except AuthenticationError:
            raise  # Não tentar novamente em erros de autenticação
        except RateLimitError:
            time.sleep(2 ** tentativa)
        except APIError as e:
            if e.status_code >= 500:
                time.sleep(1)
            else:
                raise
    raise RuntimeError("Número máximo de tentativas excedido")

Guia de Seleção de Modelos

Tarefa	Modelo	Porquê
Sumarização, classificação	gpt-4o-mini	Baixo custo
Programação geral, escrita	gpt-5.4	Melhor equilíbrio
Raciocínio complexo	gpt-5.5 ou o3	Alta capacidade
Processamento em lote	gpt-4o-mini ou gpt-5.4	Escolha pela qualidade e orçamento

Perguntas Frequentes

Como instalo a biblioteca OpenAI em Python? Execute pip install openai. Para acesso via APIMaster, nenhum pacote adicional é necessário — basta definir base_url e api_key ao inicializar o cliente.

Qual versão do Python é necessária para a biblioteca OpenAI? Python 3.8 ou superior. O cliente assíncrono requer Python 3.10+ para melhor compatibilidade.

Como lidar com limites de taxa (rate limits) da API OpenAI em Python? Use backoff exponencial — capture RateLimitError e tente novamente com atrasos crescentes. A biblioteca tenacity simplifica isso. O roteamento do APIMaster oferece estabilidade adicional.

Posso usar a biblioteca OpenAI em Python com modelos Claude? Sim — através do APIMaster. Defina base_url="https://apimaster.ai/v1" e use IDs de modelo como claude-sonnet-4-6. O formato da resposta é idêntico ao das respostas GPT.

Como usar chamadas assíncronas da OpenAI em Python? Use AsyncOpenAI em vez de OpenAI, e use await nas chamadas da API. Veja o exemplo assíncrono no guia acima.

Obtenha acesso à API OpenAI via APIMaster →