A OpenAI apagou o prazo da Assistants API do calendário: a 26 de agosto de 2026, daqui a poucos dias, a API que milhares de equipas usaram para construir os seus primeiros assistentes de IA deixa de responder. Quem ainda não migrou para a Responses API está a trabalhar contra o relógio. Este tutorial mostra, passo a passo, como configurar a API da OpenAI do zero com o GPT-5.6, o modelo lançado a 9 de julho de 2026 em três variantes (Sol, Terra e Luna), e como construir um assistente funcional com chamadas de ferramentas, streaming e gestão de custos. No final, terá um projeto completo pronto para produção.

Este guia foi escrito para programadores que já sabem Python mas nunca integraram um modelo de linguagem numa aplicação real. Cobre doze passos, do registo da conta até um assistente de suporte funcional, com erros comuns e uma tabela de resolução de problemas para quando algo correr mal a meio da implementação.

O que é a API da OpenAI e o que muda com o GPT-5.6

A API da OpenAI é a porta de entrada programática para os modelos GPT, permitindo enviar texto (ou imagens) e receber respostas geradas pelo modelo diretamente no seu código, sem passar pela interface do ChatGPT. Desde julho de 2026, o carro-chefe da família passou a ser o GPT-5.6, disponível em três tamanhos com IDs de modelo próprios: gpt-5.6-sol, gpt-5.6-terra e gpt-5.6-luna, segundo a documentação oficial de modelos da OpenAI.

Os três modelos partilham uma janela de contexto de 1,05 milhões de tokens e um limite de saída de 128 mil tokens, com data de corte de conhecimento a 16 de fevereiro de 2026. A diferença está no equilíbrio entre custo e capacidade de raciocínio: Sol é o modelo mais potente, Terra fica a meio-termo e Luna é a opção económica para tarefas simples em grande volume. Isto muda a forma como se desenha uma aplicação, porque já não faz sentido usar o modelo mais caro para tudo.

Outra mudança relevante para quem já usava a API antes de 2026: a Assistants API, lançada em 2023, está oficialmente descontinuada e será desligada a 26 de agosto de 2026, de acordo com o centro de ajuda da OpenAI. A substituta é a Responses API, que este tutorial usa do início ao fim.

Vale a pena situar o momento. O GPT-5.6 chegou poucas semanas depois de a Anthropic lançar o Claude Opus 5 e a Google atualizar o Gemini para a versão 3.7 Flash, numa sequência de lançamentos que empurrou os três maiores fornecedores de IA generativa a competir diretamente em preço por token, não apenas em qualidade de resposta. Para quem está a decidir onde construir um novo produto, isto significa que a escolha do fornecedor deixou de ser óbvia e passou a depender do perfil de utilização real da aplicação, um tema a que voltamos mais à frente neste tutorial.

Pré-requisitos antes de começar

Antes de escrever a primeira linha de código, confirme que tem isto pronto:

  • Conta na OpenAI com faturação ativa (cartão de crédito associado, mesmo que use o modelo mais barato)
  • Python 3.10 ou superior instalado (verifique com python3 --version)
  • Pacote oficial openai instalado via pip, sempre na versão mais recente disponível
  • Um editor de código (VS Code, PyCharm ou equivalente) e acesso a um terminal
  • Ligação à internet estável, já que cada chamada à API é um pedido HTTP para os servidores da OpenAI
  • Conhecimentos básicos de Python: variáveis, funções e importação de bibliotecas

Não precisa de GPU nem de hardware especial. Toda a inferência acontece nos servidores da OpenAI, o que torna este tutorial acessível mesmo num portátil modesto.

Este tutorial usa Python porque é a linguagem com a documentação mais completa e o SDK mais maduro da OpenAI, mas os mesmos conceitos aplicam-se a outras linguagens. Existem SDKs oficiais para Node.js e para .NET, além de bibliotecas mantidas pela comunidade para Go, Ruby e PHP. A estrutura dos pedidos HTTP subjacentes é idêntica em todos os casos, por isso quem entender o fluxo em Python consegue portar a lógica sem dificuldade.

Esta é também a principal diferença face a correr um modelo aberto localmente com ferramentas como o Ollama: não há download de pesos, não há gestão de VRAM e a atualização para um modelo mais recente é uma simples troca de string no código. A contrapartida é óbvia: cada pedido custa dinheiro e depende de uma ligação à internet, algo que não se aplica a um modelo a correr na sua própria máquina.

Passo 1: Criar a conta e gerar a chave de API

Aceda à plataforma de programadores da OpenAI e crie uma conta, ou inicie sessão se já tiver uma do ChatGPT. Depois de confirmar o email, entre na secção de faturação e adicione um método de pagamento: sem isto, a chave de API funciona mas todas as chamadas falham com erro de quota. Defina também um limite de gasto mensal (por exemplo, 10 ou 20 dólares) para evitar surpresas na fatura enquanto testa o código.

Depois de configurar a faturação, gere uma chave de API nova. Dê-lhe um nome descritivo, como “tutorial-gpt56”, para conseguir identificá-la mais tarde e revogá-la sem afetar outros projetos. A chave só é mostrada uma vez: copie-a de imediato para um gestor de palavras-passe ou para um ficheiro temporário seguro.

Aproveite também para criar um projeto dedicado dentro do painel da OpenAI, separado de outros projetos pessoais ou de testes antigos. Cada projeto tem o seu próprio conjunto de chaves e limites de gasto, o que facilita isolar o consumo deste tutorial de qualquer outra aplicação que já tenha em produção. Se trabalhar em equipa, este isolamento também evita que um erro de código noutro projeto esgote o orçamento reservado para o seu.

Passo 2: Instalar o SDK e configurar o ambiente com segurança

Com a chave em mãos, crie uma pasta de projeto e um ambiente virtual isolado. Isto evita conflitos entre as dependências deste projeto e outras bibliotecas Python já instaladas no seu sistema.

mkdir tutorial-openai-api
cd tutorial-openai-api
python3 -m venv venv
source venv/bin/activate   # no Windows: venv\Scripts\activate
pip install --upgrade openai python-dotenv

Nunca escreva a chave de API diretamente no código-fonte. Crie um ficheiro .env na raiz do projeto e adicione-o ao .gitignore antes de fazer o primeiro commit, para não a publicar por engano num repositório público.

# ficheiro .env
OPENAI_API_KEY=sk-a-sua-chave-aqui

No código Python, carregue a variável com python-dotenv em vez de escrever a chave literalmente. O SDK oficial da OpenAI já procura automaticamente a variável de ambiente OPENAI_API_KEY, por isso na maioria dos casos nem sequer precisa de a passar de forma explícita ao cliente.

Passo 3: A primeira chamada com a Responses API

Chegou a hora de fazer o primeiro pedido. Crie um ficheiro primeira_chamada.py com o seguinte código, que usa o modelo intermédio gpt-5.6-terra para um bom equilíbrio entre custo e qualidade durante os testes:

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()

resposta = client.responses.create(
    model="gpt-5.6-terra",
    input="Explica em duas frases o que é a Responses API da OpenAI."
)

print(resposta.output_text)

Execute com python primeira_chamada.py. Se tudo estiver bem configurado, o terminal devolve um texto semelhante a este:

A Responses API é a interface mais recente da OpenAI para gerar respostas
de IA, substituindo a Chat Completions e a Assistants API num único
formato. Suporta texto, imagens, chamadas de ferramentas e gestão de
estado da conversa através de um único objeto de resposta.

Se receber um erro de autenticação, confirme que o ficheiro .env está na mesma pasta onde executa o script e que a chave não tem espaços a mais. Trate este primeiro sucesso como o alicerce: todo o resto do tutorial constrói-se em cima desta chamada.

Vale a pena olhar com atenção para o objeto resposta devolvido pelo SDK, porque volta a aparecer em quase todos os passos seguintes. Além de output_text, que já dá acesso direto ao texto gerado, o objeto inclui resposta.id (usado para continuar a conversa), resposta.usage (com a contagem de tokens de entrada e saída) e resposta.output, uma lista que pode conter tanto texto como pedidos de chamada de ferramentas, como se vê no Passo 6. Perceber esta estrutura desde já poupa tempo de depuração mais adiante.

Passo 4: Sol, Terra ou Luna: qual modelo GPT-5.6 escolher

Escolher o modelo errado é a forma mais rápida de disparar a fatura sem ganhar qualidade percetível. A tabela seguinte resume os preços oficiais por milhão de tokens, com base na documentação de preços da OpenAI:

ModeloID na APIEntrada / 1M tokensSaída / 1M tokensMelhor para
GPT-5.6 Solgpt-5.6-sol$5,00$30,00Raciocínio complexo, código de produção, agentes multi-passo
GPT-5.6 Terragpt-5.6-terra$2,00$12,00Chatbots gerais, resumos, tarefas de negócio comuns
GPT-5.6 Lunagpt-5.6-luna$0,20$1,20Classificação, extração de dados, alto volume de pedidos

Uma prática comum em produção é usar o Luna para triagem inicial (por exemplo, classificar a intenção de uma mensagem) e só escalar para o Sol quando a tarefa exige raciocínio mais profundo. Isto pode cortar a fatura mensal de forma significativa sem sacrificar a experiência do utilizador final, porque a maioria dos pedidos reais são simples.

Um erro comum de quem vem de versões anteriores do GPT é assumir que o modelo mais caro é sempre a escolha “segura”. Na prática, tarefas como extrair um número de encomenda de uma frase ou classificar o sentimento de um comentário raramente beneficiam do raciocínio adicional do Sol, e pagar 25 vezes mais por token de entrada nesses casos não traz qualquer ganho mensurável de qualidade. A recomendação da própria documentação da OpenAI é testar primeiro com o modelo mais barato que resolve a tarefa e só subir de nível quando os resultados o justificarem.

Passo 5: Streaming de respostas em tempo real

Esperar vários segundos por uma resposta completa cria uma má experiência numa interface de chat. O streaming resolve isto, entregando os tokens à medida que o modelo os gera. Eis como ativar o modo de streaming com a Responses API:

with client.responses.stream(
    model="gpt-5.6-terra",
    input="Escreve um parágrafo curto sobre a importância de testes automatizados."
) as stream:
    for evento in stream:
        if evento.type == "response.output_text.delta":
            print(evento.delta, end="", flush=True)
    resposta_final = stream.get_final_response()

print("\n\nTokens usados:", resposta_final.usage.total_tokens)

Note o uso de flush=True na chamada a print: sem isto, o terminal pode acumular o texto em buffer e mostrar tudo de uma vez, anulando o efeito visual do streaming. Em aplicações web, o mesmo padrão aplica-se através de Server-Sent Events ou WebSockets, enviando cada fragmento assim que chega do servidor da OpenAI.

Passo 6: Function calling: ligar o modelo a ferramentas externas

A funcionalidade que transforma um simples gerador de texto num agente capaz de agir é o function calling. Descreve-se uma função em JSON Schema e o modelo decide, sozinho, quando a deve invocar. Um exemplo prático: uma função que consulta o estado de uma encomenda.

ferramentas = [{
    "type": "function",
    "name": "consultar_encomenda",
    "description": "Devolve o estado atual de uma encomenda pelo número de referência.",
    "parameters": {
        "type": "object",
        "properties": {
            "numero_encomenda": {"type": "string", "description": "Referência da encomenda"}
        },
        "required": ["numero_encomenda"]
    }
}]

resposta = client.responses.create(
    model="gpt-5.6-sol",
    input="Qual é o estado da encomenda PT-88213?",
    tools=ferramentas
)

for item in resposta.output:
    if item.type == "function_call":
        print("Função pedida:", item.name)
        print("Argumentos:", item.arguments)

O modelo não executa a função por si próprio: devolve a intenção e os argumentos, cabe ao seu código correr a lógica real (consultar uma base de dados, chamar outra API) e enviar o resultado de volta ao modelo numa segunda chamada, para que ele formule a resposta final em linguagem natural. Este ciclo de pedido-execução-resposta é o núcleo de praticamente todos os agentes construídos sobre a API da OpenAI em 2026.

Nunca assuma que os argumentos devolvidos são válidos. O modelo pode, ocasionalmente, gerar um JSON incompleto ou um valor fora do formato esperado, sobretudo em respostas mais longas. Envolva sempre a leitura dos argumentos num bloco de tratamento de exceções:

import json

for item in resposta.output:
    if item.type == "function_call":
        try:
            args = json.loads(item.arguments)
        except json.JSONDecodeError:
            print("Argumentos inválidos recebidos, a pedir esclarecimento ao modelo")
            continue

        if "numero_encomenda" not in args:
            print("Campo obrigatório em falta nos argumentos")
            continue

        print("Argumentos válidos:", args)

Esta validação extra parece exagerada nos primeiros testes, mas torna-se essencial assim que a função ligada ao modelo tem efeitos reais, como processar um pagamento ou apagar um registo numa base de dados.

Passo 7: Gerir conversas multi-turno e o histórico

Um chatbot só é útil se se lembrar do que foi dito antes. A Responses API simplifica isto com o parâmetro previous_response_id, que evita reenviar todo o histórico a cada pedido:

primeira = client.responses.create(
    model="gpt-5.6-terra",
    input="Chamo-me Rita e trabalho com análise de dados."
)

segunda = client.responses.create(
    model="gpt-5.6-terra",
    input="Qual é a minha profissão?",
    previous_response_id=primeira.id
)

print(segunda.output_text)  # deve mencionar "análise de dados"

Para conversas longas ou com muitos utilizadores em simultâneo, guarde apenas o previous_response_id mais recente por utilizador na sua base de dados, em vez de armazenar o texto completo da conversa. Isto reduz drasticamente o volume de dados que o seu backend precisa de gerir.

Há uma implicação de custo a ter em conta: mesmo usando previous_response_id, o histórico completo da conversa continua a contar para o total de tokens de entrada processados pelo modelo em cada novo pedido, porque a OpenAI reconstrói o contexto internamente. Numa conversa de suporte que se arrasta por vinte ou trinta mensagens, isto pode aproximar-se do limiar de contexto longo referido no Passo 9, com o consequente aumento de preço por token. Para conversas com tendência a alongar-se, vale a pena implementar um resumo periódico do histórico antigo, substituindo mensagens de há muitas trocas por uma síntese curta.

Passo 8: Migrar da Assistants API antes do encerramento de 26 de agosto

Se o seu projeto ainda usa client.beta.assistants ou client.beta.threads, tem de agir já. A OpenAI confirmou no seu centro de ajuda que a Assistants API será removida a 26 de agosto de 2026, sem novas funcionalidades desde essa data em diante. A boa notícia é que a maioria dos conceitos tem equivalente direto na Responses API:

  • Um “thread” da Assistants API corresponde a uma cadeia de previous_response_id na Responses API
  • As “instruções” de um assistente passam a ser o parâmetro instructions em cada chamada a responses.create
  • As “ferramentas” (function calling, pesquisa de ficheiros) mantêm uma estrutura muito semelhante, com pequenos ajustes de nomenclatura
  • Os “runs” assíncronos deixam de ser necessários: a Responses API devolve o resultado diretamente ou via streaming

Em código, a diferença fica mais clara lado a lado. Onde antes criava um assistente, depois um thread e depois um run, com a Responses API o mesmo resultado sai de uma única chamada:

# Antes (Assistants API, descontinuada)
# assistant = client.beta.assistants.create(model="gpt-5.6-terra", instructions="...")
# thread = client.beta.threads.create()
# client.beta.threads.messages.create(thread.id, role="user", content="...")
# run = client.beta.threads.runs.create(thread.id, assistant_id=assistant.id)

# Agora (Responses API)
resposta = client.responses.create(
    model="gpt-5.6-terra",
    instructions="...",
    input="..."
)

Comece a migração pelos endpoints com menor tráfego, valide o comportamento em ambiente de testes e só depois substitua os fluxos críticos. Deixar isto para os últimos dias antes do encerramento é o erro mais caro que uma equipa pode cometer neste momento.

Passo 9: Controlar custos – tokens, cache e contexto longo

Os preços mudam consoante o tamanho do pedido. Para contextos curtos aplicam-se as tarifas normais, mas a OpenAI cobra mais quando o pedido ultrapassa o limiar de contexto longo. Também existe desconto automático para tokens em cache, ou seja, partes do prompt que se repetem entre chamadas (como instruções de sistema fixas).

ComponenteGPT-5.6 Sol (contexto curto)GPT-5.6 Sol (contexto longo)
Entrada normal$5,00 / 1M tokens$10,00 / 1M tokens
Entrada em cache$0,50 / 1M tokens$1,00 / 1M tokens
Escrita em cache$6,25 / 1M tokens$12,50 / 1M tokens
Saída$30,00 / 1M tokens$45,00 / 1M tokens

Na prática, isto significa três hábitos que valem a pena adotar: manter as instruções de sistema estáveis entre chamadas para beneficiar do cache, escolher o modelo mais barato que resolve a tarefa (voltando ao Passo 4) e monitorizar o campo usage devolvido em cada resposta para detetar picos de consumo antes que apareçam na fatura mensal.

O desconto de cache não é automático em todos os casos: só se aplica quando o início do prompt é idêntico entre chamadas consecutivas. Se cada pedido começar com um preâmbulo ligeiramente diferente (por exemplo, com a data atual inserida dinamicamente no início do texto), o cache nunca chega a ativar-se. A solução simples é colocar o conteúdo variável no fim do prompt e manter as instruções fixas sempre no início.

Passo 10: Tratamento de erros, retries e limites de taxa

Chamadas de rede falham: picos de tráfego, quebras momentâneas de ligação ou limites de taxa da própria conta. Um código de produção precisa de lidar com isto sem deixar a aplicação em erro para o utilizador final.

import time
from openai import OpenAI, RateLimitError, APIConnectionError

client = OpenAI()

def chamar_com_retry(prompt, tentativas=3):
    for tentativa in range(tentativas):
        try:
            return client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
        except RateLimitError:
            espera = 2 ** tentativa
            print(f"Limite de taxa atingido, a aguardar {espera}s...")
            time.sleep(espera)
        except APIConnectionError:
            print("Falha de ligação, a tentar novamente...")
            time.sleep(2)
    raise Exception("Falhou após várias tentativas")

Este padrão de espera exponencial (dobrar o tempo de espera a cada tentativa falhada) é o standard da indústria para lidar com limites de taxa, e evita sobrecarregar ainda mais um serviço que já está sob pressão. Os limites concretos de pedidos por minuto variam consoante o nível de utilização da conta, que pode ser consultado diretamente no painel de faturação da OpenAI.

Passo 11: Testar e validar a integração

Antes de expor a integração a utilizadores reais, escreva um punhado de testes automatizados que cubram os casos mais comuns: uma pergunta simples, uma pergunta que deve acionar uma função, uma entrada vazia e uma entrada muito longa. Isto detecta regressões quando trocar de modelo ou ajustar as instruções de sistema.

def teste_resposta_basica():
    resposta = client.responses.create(
        model="gpt-5.6-luna",
        input="Diz apenas a palavra 'ok'."
    )
    assert "ok" in resposta.output_text.lower()
    print("Teste básico: OK")

teste_resposta_basica()

Corra estes testes num ambiente de integração contínua antes de cada implementação, usando sempre o modelo Luna para manter os custos de teste próximos de zero enquanto valida apenas a estrutura da integração, não a qualidade das respostas do modelo mais caro.

Para testar o fluxo de function calling sem depender da variabilidade do modelo, escreva também um teste que simula diretamente a resposta da API, sem gastar tokens reais:

from unittest.mock import MagicMock

def teste_deteta_function_call():
    resposta_simulada = MagicMock()
    resposta_simulada.output = [
        MagicMock(type="function_call", name="consultar_encomenda", arguments='{"numero_encomenda": "PT-88213"}')
    ]

    encontrou = any(item.type == "function_call" for item in resposta_simulada.output)
    assert encontrou is True
    print("Teste de deteção de function call: OK")

teste_deteta_function_call()

Este tipo de teste simulado corre em milissegundos e não consome quota da API, o que o torna ideal para correr centenas de vezes por dia num pipeline de integração contínua sem impacto na fatura.

Passo 12: Projeto completo – assistente de suporte com function calling

Juntando tudo o que foi visto, eis um assistente de suporte ao cliente funcional, com histórico de conversa, uma ferramenta real e tratamento básico de erros:

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()

BASE_DADOS_ENCOMENDAS = {
    "PT-88213": "Em trânsito, entrega prevista para amanhã",
    "PT-77102": "Entregue a 18 de agosto"
}

ferramentas = [{
    "type": "function",
    "name": "consultar_encomenda",
    "description": "Devolve o estado de uma encomenda pela referência.",
    "parameters": {
        "type": "object",
        "properties": {"numero_encomenda": {"type": "string"}},
        "required": ["numero_encomenda"]
    }
}]

def assistente_suporte(mensagem_utilizador, id_resposta_anterior=None):
    resposta = client.responses.create(
        model="gpt-5.6-terra",
        instructions="És um assistente de suporte ao cliente simpático e direto. Usa a ferramenta consultar_encomenda quando o cliente perguntar pelo estado de uma encomenda.",
        input=mensagem_utilizador,
        tools=ferramentas,
        previous_response_id=id_resposta_anterior
    )

    for item in resposta.output:
        if item.type == "function_call" and item.name == "consultar_encomenda":
            import json
            args = json.loads(item.arguments)
            estado = BASE_DADOS_ENCOMENDAS.get(args["numero_encomenda"], "referência não encontrada")

            resposta_final = client.responses.create(
                model="gpt-5.6-terra",
                previous_response_id=resposta.id,
                input=[{
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": estado
                }]
            )
            return resposta_final

    return resposta

r1 = assistente_suporte("Olá, qual é o estado da encomenda PT-88213?")
print(r1.output_text)

Este esqueleto já cobre autenticação, escolha de modelo, function calling, histórico de conversa e uma base de dados simulada. Para produção, substitua o dicionário Python por uma consulta real a uma base de dados e adicione o tratamento de erros do Passo 10. Também vale a pena expor esta função através de um pequeno servidor web, com FastAPI ou Flask, para que o assistente possa ser chamado a partir de um site ou de uma aplicação móvel em vez de correr apenas no terminal.

Erros comuns ao integrar a API da OpenAI

  • Guardar a chave de API no código-fonte: qualquer pessoa com acesso ao repositório (ou a um leak acidental no GitHub) pode usá-la e gastar o seu saldo em minutos.
  • Usar o modelo Sol para tudo: a diferença de preço entre Sol e Luna é de 25x na entrada, um custo desnecessário para tarefas simples de classificação.
  • Ignorar o campo usage: sem monitorizar tokens consumidos por pedido, é impossível prever a fatura antes de ela chegar.
  • Reenviar todo o histórico manualmente: em vez de usar previous_response_id, muitos programadores reconstroem o histórico à mão, o que dispara o custo de entrada em conversas longas.
  • Não tratar erros de limite de taxa: uma aplicação que rebenta com RateLimitError na primeira falha perde utilizadores logo no primeiro pico de tráfego.
  • Confiar cegamente nos argumentos de uma function call: o modelo pode gerar argumentos malformados. Valide sempre antes de executar a função correspondente.

Nenhum destes erros é exclusivo de principiantes. Equipas experientes voltam a cair na tentação de usar o modelo mais caro “por segurança” ou de adiar o tratamento de limites de taxa até um pico de tráfego real os apanhar de surpresa. Reveja esta lista antes de cada lançamento importante, não apenas na primeira integração.

Resolução de problemas

Estes são os problemas mais reportados por quem começa a usar a API da OpenAI, com a causa provável e a correção. Guarde esta tabela por perto durante as primeiras semanas de uso, porque a maioria destes sintomas repete-se em fases distintas do desenvolvimento, do primeiro teste local ao primeiro pico de tráfego em produção:

SintomaCausa provávelCorreção
AuthenticationErrorChave inválida, revogada ou ficheiro .env não carregadoConfirmar load_dotenv() antes de instanciar o cliente e gerar nova chave se necessário
RateLimitError constanteVolume de pedidos acima do nível da contaImplementar espera exponencial e considerar subir de nível de faturação
Resposta vazia (output_text vazio)O modelo devolveu apenas uma function_call, sem textoVerificar o tipo de cada item em resposta.output antes de assumir texto
InsufficientQuotaErrorSem método de pagamento ativo ou saldo pré-pago esgotadoAdicionar cartão de crédito ou recarregar saldo na secção de faturação
Custos muito acima do esperadoUso do modelo Sol em tarefas simples ou contexto longo repetido sem cacheRever a tabela de modelos do Passo 4 e ativar reutilização de prompt em cache
Erro de JSON Schema inválido na ferramentaEstrutura de parameters mal formadaValidar o schema com um validador JSON antes de o enviar na chamada
Timeout em pedidos longosContexto muito extenso sem streaming ativadoAtivar client.responses.stream() para receber tokens progressivamente
Assistants API deixou de funcionarEncerramento a 26 de agosto de 2026Migrar para a Responses API seguindo o Passo 8

Dicas avançadas para produção

Depois de dominar o básico, estas práticas fazem a diferença entre um protótipo e um sistema fiável. Primeiro, separe as instruções de sistema por caso de uso num ficheiro de configuração próprio, em vez de as espalhar pelo código: facilita testar variações e reverter alterações que piorem a qualidade das respostas.

Segundo, registe cada pedido e resposta (sem dados sensíveis) num sistema de logs próprio, para conseguir reproduzir problemas reportados por utilizadores semanas depois. Terceiro, implemente um circuito de fallback: se o Sol falhar ou demorar demasiado, tente automaticamente com o Terra antes de mostrar um erro ao utilizador. Por fim, quando a aplicação crescer para múltiplas ferramentas, considere um limite máximo de “saltos” entre function calls, para evitar que o modelo entre num ciclo de chamadas sem nunca chegar a uma resposta final em texto.

Duas práticas adicionais fazem diferença à medida que o tráfego cresce. A primeira é isolar as chamadas à API num módulo próprio da aplicação, com uma interface única, para poder trocar de modelo, ajustar parâmetros de retry ou adicionar cache sem tocar no resto do código. A segunda é acompanhar o custo por utilizador, não só o custo total: um único cliente com um bot mal configurado a repetir pedidos pode inflacionar a fatura sem que a média geral pareça alarmante.

Checklist antes de lançar em produção

Antes de anunciar a funcionalidade aos utilizadores finais, percorra esta lista. Cobre os pontos que mais frequentemente falham numa primeira implementação da API da OpenAI:

  • A chave de API está apenas em variáveis de ambiente, nunca em código-fonte ou em ficheiros de configuração versionados
  • Existe um limite de gasto mensal definido no painel de faturação, ajustado ao orçamento real do projeto
  • O tratamento de erros cobre pelo menos RateLimitError, APIConnectionError e AuthenticationError
  • As respostas com function calls são validadas antes de qualquer ação com efeitos reais ser executada
  • O modelo escolhido para cada tipo de tarefa foi testado contra pelo menos uma alternativa mais barata
  • Existem logs de pedidos e respostas para permitir depuração posterior, sem armazenar dados pessoais desnecessários
  • O código não depende de nenhum endpoint da Assistants API que deixe de funcionar a 26 de agosto de 2026

Se todos estes pontos estiverem confirmados, a integração está pronta para lidar com tráfego real sem sustos na primeira semana em produção. Trate esta lista como um documento vivo: à medida que a equipa aprende com incidentes reais, acrescente novos itens específicos ao contexto da sua aplicação.

OpenAI vs Claude vs Gemini: qual API escolher

A escolha entre fornecedores raramente é absoluta: muitas equipas usam mais do que um. Esta tabela compara os preços oficiais atuais dos três principais concorrentes, com dados de agosto de 2026:

FornecedorModelo de referênciaEntrada / 1M tokensSaída / 1M tokensContexto
OpenAIGPT-5.6 Sol$5,00$30,001,05M tokens
AnthropicClaude Opus 5$5,00$25,001M tokens
GoogleGemini 3.7 Flash$0,75 (promo até 31 dez 2026)$3,75 (promo até 31 dez 2026)1M tokens

O preço promocional do Gemini 3.7 Flash sobe para $1,50 de entrada e $7,50 de saída a partir de 1 de janeiro de 2027, segundo a documentação oficial da Google. Já compará­mos a fundo a integração da API Claude e da API Gemini em tutoriais anteriores, caso queira aprofundar as alternativas antes de decidir.

Na prática, cada fornecedor tende a destacar-se num cenário diferente. O GPT-5.6 Sol e o Claude Opus 5 ficam empatados no preço de entrada, mas o Opus 5 sai mais barato na saída, o que pesa em tarefas que geram muito texto, como redação longa ou documentação técnica. O Gemini 3.7 Flash, por seu lado, é claramente o mais barato dos três enquanto durar o preço promocional, o que o torna atrativo para aplicações de alto volume e baixa margem, como classificação em massa ou moderação de conteúdo. Nenhuma das três é universalmente “melhor”: a escolha certa depende do volume esperado, da complexidade das tarefas e de quanto raciocínio multi-passo a aplicação realmente precisa.

Perguntas frequentes

Quanto custa começar a usar a API da OpenAI?

Não há custo de entrada fixo: paga apenas pelos tokens que consumir. Com o modelo Luna a $0,20 por milhão de tokens de entrada, é possível testar a integração completa por menos de um euro.

Preciso mesmo de migrar da Assistants API já?

Sim. A OpenAI confirmou o encerramento para 26 de agosto de 2026. Depois dessa data, chamadas à Assistants API deixam de funcionar por completo, o que significa que qualquer aplicação em produção que ainda dependa dela vai deixar de responder aos utilizadores sem aviso adicional.

Qual a diferença entre Chat Completions e Responses API?

A Chat Completions continua disponível, mas a Responses API é a via recomendada pela OpenAI para novos projetos, por unificar texto, ferramentas e gestão de estado da conversa num único formato mais simples.

Posso usar a API da OpenAI gratuitamente?

Não existe nível gratuito permanente para a API (ao contrário da interface do ChatGPT). É necessário adicionar um método de pagamento antes de fazer a primeira chamada.

Como escolho entre Sol, Terra e Luna?

Comece pelo Terra para a maioria das tarefas, já que oferece o melhor equilíbrio entre custo e qualidade para uso geral. Suba para o Sol apenas quando notar que as respostas ficam aquém do esperado em tarefas complexas, como raciocínio matemático ou análise jurídica, e desça para o Luna em tarefas repetitivas e simples, como classificação de texto ou extração de campos.

O function calling funciona com todos os modelos GPT-5.6?

Sim, os três modelos da família suportam chamadas de ferramentas através do mesmo parâmetro tools na Responses API.

Como evito exceder o orçamento definido?

Defina um limite de gasto mensal no painel de faturação, monitorize o campo usage em cada resposta e prefira o modelo mais barato que resolve cada tarefa específica.

É seguro guardar a chave de API num ficheiro .env?

É a prática recomendada, desde que o ficheiro .env nunca seja submetido a um repositório de código. Adicione-o sempre ao .gitignore antes do primeiro commit do projeto.

Cobertura Relacionada

Fontes oficiais consultadas para os preços e especificações técnicas deste tutorial: documentação de preços da OpenAI, catálogo de modelos da OpenAI, preços da API Claude, preços da API Gemini e o repositório oficial do SDK Python no GitHub.