O Que e a API da OpenAI e Para Que Serve?

A API da OpenAI e a porta de entrada para integrar modelos de linguagem avancados -- como GPT-4o, o3 e seus derivados -- diretamente em aplicacoes, scripts e pipelines de dados. Em vez de usar o ChatGPT pelo navegador, voce programa a inteligencia: define o comportamento do modelo via codigo, controla o contexto, automatiza tarefas e integra tudo ao seu sistema.

Para que ela e usada na pratica? Geracao de texto e resumos, analise e classificacao de documentos, chatbots com memoria, processamento de imagens, criacao de embeddings para busca semantica, extracao estruturada de dados, geracao de codigo e muito mais.

Se voce e desenvolvedor Python, a API da OpenAI e uma das ferramentas mais poderosas que voce pode adicionar ao seu kit. Este guia cobre tudo do zero: conta, chave, primeiro request, streaming, visao, embeddings e um chatbot completo com historico de conversa.

---

Modelos: GPT-4o, GPT-4o-mini, o3, o4-mini

A OpenAI disponibiliza uma familia de modelos com diferentes balances de custo, velocidade e capacidade. A tabela abaixo usa precos aproximados de 2025 (por 1 milhao de tokens):

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

| gpt-4o | 128k | $2,50 | $10,00 | Multimodal, mais capaz para tarefas complexas |

| gpt-4o-mini | 128k | $0,15 | $0,60 | Custo ultra-baixo, rapido, otimo para alto volume |

| o3 | 200k | $10,00 | $40,00 | Raciocinio profundo, ciencia, matematica, codigo |

| o4-mini | 200k | $1,10 | $4,40 | Raciocinio avancado a custo razoavel |

| gpt-4.1 | 1M | $2,00 | $8,00 | Contexto gigante, bom para documentos longos |

Regra geral: comece com gpt-4o-mini para prototipos e alto volume. Use gpt-4o quando precisar de qualidade maxima em tarefas complexas. Recorra a o3/o4-mini para raciocinio passo a passo (matematica, codigo intrincado, logica).

Sempre verifique a pagina de precos da OpenAI antes de escolher.

---

Configuracao: Conta, API Key e Ambiente Python

1. Criando a conta e obtendo a API Key

1. Acesse platform.openai.com e crie uma conta.

2. Adicione creditos em Billing > Add payment method.

3. Va em API keys > Create new secret key. Copie a chave -- ela so aparece uma vez.

2. Instalando o SDK Python

pip install openai

3. Configurando a chave no ambiente

Nunca coloque a chave diretamente no codigo. Use variaveis de ambiente:

# Linux/macOS
export OPENAI_API_KEY="sk-proj-..."

# Windows PowerShell
$env:OPENAI_API_KEY="sk-proj-..."

Ou crie um arquivo .env e use python-dotenv:

pip install python-dotenv

# .env
OPENAI_API_KEY=sk-proj-...

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

---

Seu Primeiro Request: Chat Completions

O endpoint central da API e /v1/chat/completions. Voce envia uma lista de mensagens e recebe a resposta do modelo.

from openai import OpenAI

client = OpenAI()  # le OPENAI_API_KEY automaticamente

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Voce e um assistente especializado em Python."},
        {"role": "user", "content": "Explique o que e um decorator em Python com um exemplo simples."}
    ]
)

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

Estrutura da resposta:

response.choices[0].message.content -- o texto gerado
response.usage.prompt_tokens -- tokens da entrada
response.usage.completion_tokens -- tokens gerados
response.model -- modelo exato utilizado

---

Parametros: temperature, max_tokens, system

temperature

Controla a criatividade do modelo. Valores entre 0 e 2.

0 -> respostas deterministicas, ideais para extracao de dados e codigo
0.7 -> balance entre coerencia e variedade (padrao razoavel)
1.5+ -> respostas mais criativas e imprevisíveis

response = client.chat.completions.create(
    model="gpt-4o-mini",
    temperature=0.2,
    messages=[{"role": "user", "content": "Classifique este e-mail como spam ou nao spam."}]
)

max_tokens (max_completion_tokens)

Limita o tamanho da resposta. Util para controlar custo.

response = client.chat.completions.create(
    model="gpt-4o",
    max_completion_tokens=500,
    messages=[{"role": "user", "content": "Resuma este artigo em 3 paragrafos."}]
)

system prompt

A mensagem com "role": "system" define o comportamento global do assistente. E a instrucao mais importante -- use-a para definir persona, tom, formato de resposta e restricoes.

messages = [
    {
        "role": "system",
        "content": "Voce e um especialista em SQL. Responda sempre com exemplos de codigo. Nao faca suposicoes."
    },
    {"role": "user", "content": "Como faco um JOIN com tres tabelas?"}
]

---

Streaming de Respostas

Streaming envia tokens conforme sao gerados, em vez de aguardar a resposta completa. Ideal para interfaces de chat onde o usuario ve o texto sendo exibido progressivamente.

from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    stream=True,
    messages=[{"role": "user", "content": "Escreva um poema curto sobre Python."}]
)

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

print()  # nova linha ao final

Para capturar o texto completo durante o streaming:

full_response = ""

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

print(f"Resposta completa: {len(full_response)} chars")

---

Processamento de Imagens (Vision)

O GPT-4o aceita imagens como entrada. Voce pode enviar uma URL publica ou a imagem codificada em base64.

Via URL publica

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "O que ha nesta imagem? Descreva em detalhes."},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/imagem.jpg"}
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

Via base64 (imagem local)

import base64

def encode_image(image_path: str) -> str:
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

image_data = encode_image("screenshot.png")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Quais sao os erros visiveis neste screenshot?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}",
                        "detail": "high"
                    }
                }
            ]
        }
    ]
)

O parametro detail controla a resolucao: "low" e mais barato, "high" examina a imagem em tiles para maior precisao.

---

Embeddings e Busca Semantica

Embeddings transformam texto em vetores numericos que capturam significado semantico. Textos similares ficam proximos no espaco vetorial -- o que viabiliza busca por similaridade, clustering e recomendacoes.

import numpy as np
from openai import OpenAI

client = OpenAI()

def get_embedding(text: str, model: str = "text-embedding-3-small") -> list:
    response = client.embeddings.create(input=text, model=model)
    return response.data[0].embedding

def cosine_similarity(a: list, b: list) -> float:
    a, b = np.array(a), np.array(b)
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

documentos = [
    "Python e uma linguagem de programacao versatil.",
    "O GPT-4o e um modelo multimodal da OpenAI.",
    "Machine learning usa dados para treinar modelos.",
    "Django e um framework web para Python.",
]

query = "Qual framework web usar com Python?"

embeddings_docs = [get_embedding(doc) for doc in documentos]
embedding_query = get_embedding(query)

similaridades = [
    (doc, cosine_similarity(embedding_query, emb))
    for doc, emb in zip(documentos, embeddings_docs)
]

similaridades.sort(key=lambda x: x[1], reverse=True)

for doc, score in similaridades:
    print(f"[{score:.3f}] {doc}")

Modelos de embedding disponiveis:

| Modelo | Dimensoes | Custo ($/M tokens) |

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

| text-embedding-3-small | 1536 | $0,02 |

| text-embedding-3-large | 3072 | $0,13 |

| text-embedding-ada-002 | 1536 | $0,10 (legado) |

---

Gerenciamento de Custos e Rate Limits

Monitorando gastos

Sempre registre o uso de tokens para controlar custos:

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

usage = response.usage
custo_input = (usage.prompt_tokens / 1_000_000) * 0.15
custo_output = (usage.completion_tokens / 1_000_000) * 0.60
print(f"Custo estimado: US$ {custo_input + custo_output:.6f}")

Rate limits

A OpenAI limita requisicoes por minuto (RPM) e tokens por minuto (TPM). Se voce ultrapassar, recebera erro 429. Trate com exponential backoff:

import time
import random
from openai import RateLimitError

def completions_with_retry(client, **kwargs):
    max_retries = 5
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limit. Aguardando {wait:.1f}s...")
            time.sleep(wait)

Boas praticas de custo

Use gpt-4o-mini para tarefas de classificacao, extracao simples e alto volume
Defina max_completion_tokens para evitar respostas excessivamente longas
Cache responses para perguntas repetidas (Redis, banco de dados)
Monitore via dashboard em platform.openai.com/usage

---

Exemplo Completo: Chatbot com Historico

Este exemplo cria um chatbot em linha de comando com historico de conversa persistido na sessao:

from openai import OpenAI

client = OpenAI()

def criar_chatbot(system_prompt: str = "Voce e um assistente util e direto."):
    historico = [{"role": "system", "content": system_prompt}]

    def chat(mensagem: str) -> str:
        historico.append({"role": "user", "content": mensagem})

        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=historico,
            temperature=0.7,
            max_completion_tokens=1000
        )

        resposta = response.choices[0].message.content
        historico.append({"role": "assistant", "content": resposta})

        # Evitar contexto muito longo (manter system + ultimas 20 mensagens)
        if len(historico) > 22:
            historico[1:3] = []

        return resposta

    return chat

def main():
    print("=== Chatbot OpenAI ===")
    print("Digite 'sair' para encerrar.")

    system = input("System prompt (Enter para padrao): ").strip()
    chat = criar_chatbot(system or "Voce e um assistente util e direto.")

    while True:
        try:
            mensagem = input("Voce: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("Encerrando...")
            break

        if mensagem.lower() == "sair":
            break

        if not mensagem:
            continue

        resposta = chat(mensagem)
        print(f"Assistente: {resposta}")

if __name__ == "__main__":
    main()

Para rodar: python chatbot.py

Este codigo gerencia o historico automaticamente, trunca conversas longas para evitar ultrapassar o limite de contexto e lida com interrupcao pelo teclado de forma elegante.

---

Perguntas Frequentes

1. Quanto custa usar a API da OpenAI?

Depende do modelo e do volume. Para uso casual com gpt-4o-mini, mil mensagens de tamanho medio custam menos de R$ 0,50. Para projetos de alto volume, defina limites de gasto em Billing > Usage limits no dashboard.

2. A API da OpenAI e diferente do ChatGPT Plus?

Sim. O ChatGPT Plus e uma assinatura para usar o chat no navegador. A API e cobrada por uso (tokens) e da acesso programatico aos modelos -- sem interface, so codigo.

3. Como evitar que a API Key vaze?

Nunca commite a chave no git. Use .gitignore para o .env, prefira variaveis de ambiente do sistema, e configure um limite de gasto no dashboard como failsafe.

4. Posso usar a API em producao sem restricoes?

Sim, mas observe os limites de rate (RPM/TPM) do seu tier. Contas novas tem limites menores -- eles aumentam conforme seu historico de uso.

5. Qual e a diferenca entre gpt-4o e o3?

gpt-4o e um modelo de uso geral, rapido e multimodal. o3 e um modelo de raciocinio -- ele pensa mais antes de responder, e muito mais lento, caro, e excelente para problemas que exigem logica encadeada.

6. Como estruturar o system prompt para melhores resultados?

Seja especifico sobre persona, formato de resposta, restricoes e exemplos. Um bom system prompt define: quem o modelo e, o que ele deve/nao deve fazer, e como deve formatar a saida.

Como Usar a API da OpenAI com Python