Ir para o conteúdo principal
Português— Escolher um idioma
Menu

A Sua Primeira Chamada à API

Aula 5 de 22 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A Sua Primeira Chamada à API
  2. A Chamada Mais Simples
  3. O Que a Resposta Contém Realmente
  4. Os Parâmetros Que Importam
  5. Passar Para Entrada Estruturada
  6. Nunca Deixe Uma Chamada Desprotegida
  7. Pontos-chave

Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_effort="none" (Completions de Chat). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

A Sua Primeira Chamada à API

O seu ambiente está pronto: vamos ao trabalho. Está prestes a efetuar a sua primeira chamada à API de Respostas, dissecar o objeto que esta devolve e, em seguida, manipular os parâmetros que separam uma resposta genérica de uma resposta útil.

A Chamada Mais Simples

Só precisa de dois parâmetros: model, o identificador do modelo a consultar, e input, o seu prompt — seja uma cadeia de texto ou uma lista de mensagens, como verá brevemente.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the difference between Python and JavaScript?"
)

print(response.output_text)
# Resultado: Python is a versatile language oriented toward data science
# and backend development, while JavaScript is primarily used for
# frontend and backend web development (via Node.js)...

O Que a Resposta Contém Realmente

output_text é apenas um atalho de conveniência. O objeto response também contém o seu ID único — essencial para encadear trocas e consultar chamadas nos seus registos —, o modelo real utilizado e uma desagregação do consumo de tokens. Habitue-se a registar estas três informações desde os seus primeiros scripts. É isto que lhe permitirá responder mais tarde à pergunta: «Por que razão a fatura duplicou este mês?»

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Hello, how are you?"
)

# O texto da resposta (atalho)
print(response.output_text)

# O ID único da resposta
print(f"ID: {response.id}")

# O modelo utilizado
print(f"Modelo: {response.model}")

# Tokens consumidos
print(f"Tokens de entrada: {response.usage.input_tokens}")
print(f"Tokens de saída: {response.usage.output_tokens}")
print(f"Total de tokens: {response.usage.total_tokens}")

# Resultado:
# Hello! I'm doing very well, thank you. How can I help you?
# ID: resp_abc123xyz
# Modelo: gpt-5.6-terra
# Tokens de entrada: 14
# Tokens de saída: 19
# Total de tokens: 33

Os Parâmetros Que Importam

temperature governa a variabilidade da geração. Em 0.0, o modelo escolhe sistematicamente a continuação mais provável: esta é a configuração para perguntas factuais, extração de dados e tudo o que necessite de reproduzir identicamente. Em 1.0, explora mais, o que é desejável para naming, escrita criativa ou geração de variantes.

# Temperatura baixa (0.0) = determinístico, factual
response_factual = client.responses.create(
    model="gpt-5.6-terra",
    reasoning={"effort": "none"},  # temperature requires effort none
    input="What is the capital of Germany?",
    temperature=0.0
)
print(response_factual.output_text)
# Resultado: The capital of Germany is Berlin.

# Temperatura alta (1.0) = criativo, variado
response_creative = client.responses.create(
    model="gpt-5.6-terra",
    reasoning={"effort": "none"},  # temperature requires effort none
    input="Invent a name for a literary café.",
    temperature=1.0
)
print(response_creative.output_text)
# Resultado: "The Wandering Pages"—a café where every table bears
# the name of a famous chapter.

O parâmetro instructions desempenha o papel da antiga mensagem de sistema: define o papel, o tom e as restrições que o modelo deve manter durante toda a troca, independentemente da pergunta feita. No exemplo abaixo, a mesma pergunta feita sem instruções produziria uma lista de dicas gerais; com elas, produz receitas.

response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="You are an expert in French cuisine. "
                 "Always respond with recipe suggestions.",
    input="I don't know what to do with zucchini."
)
print(response.output_text)
# Resultado: Here are three ideas for your zucchini:
# 1. Zucchini gratin with goat cheese...
# 2. Provençal ratatouille...
# 3. Cold zucchini velouté with mint...

Finalmente, max_output_tokens limita o comprimento da resposta. Trata-se de uma salvaguarda orçamental, não de uma instrução de escrita: a resposta é cortada abruptamente assim que o limite é atingido. Se quiser uma resposta curta e bem formada, peça-o também no prompt.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Explain general relativity.",
    max_output_tokens=100
)
print(response.output_text)
print(f"Tokens utilizados: {response.usage.output_tokens}")
# A resposta será truncada a aproximadamente 100 tokens

Passar Para Entrada Estruturada

Quando uma simples cadeia de texto não é suficiente, input aceita uma lista de mensagens. A forma mínima contém um único turno, mas o benefício surge assim que fornece histórico: o modelo tem então acesso ao que já foi dito e responde em conformidade. Aqui, «progresso» entende-se no contexto de Python, não de forma abstrata.

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": "Translate to English: Hello world"
        }
    ]
)
print(response.output_text)
# Resultado: Hello world

# Com contexto de conversação
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": "My favorite language is Python."
        },
        {
            "role": "assistant",
            "content": "Python is an excellent choice! It is very versatile."
        },
        {
            "role": "user",
            "content": "Give me a tip to improve."
        }
    ]
)
print(response.output_text)
# Resultado: To improve in Python, I recommend that you...

Nunca Deixe Uma Chamada Desprotegida

As chamadas de rede falham e as chaves expiram. Três exceções cobrem a maioria dos casos ao começar: AuthenticationError para uma chave em falta ou inválida, RateLimitError quando excede a sua taxa permitida e APIError como rede de segurança genérica. Uma lição inteira retomará a estratégia completa, mas, a partir de hoje, envolva as suas chamadas.

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="Hello!"
    )
    print(response.output_text)
except AuthenticationError:
    print("Erro: Chave API inválida ou em falta")
except RateLimitError:
    print("Erro: Demasiados pedidos, aguarde um momento")
except APIError as e:
    print(f"Erro da API: {e.message}")

Para consolidar tudo isto, escreva um script que faça três perguntas e acumule os tokens consumidos. Combinará o ciclo de chamadas, uma temperatura de 0.0 para respostas estáveis e a leitura de usage — os três reflexos básicos.

from openai import OpenAI

client = OpenAI()

questions = [
    "What is the largest ocean in the world?",
    "Who painted the Mona Lisa?",
    "How many planets are in the solar system?"
]

total_tokens = 0

for question in questions:
    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=question,
        temperature=0.0
    )
    tokens = response.usage.total_tokens
    total_tokens += tokens
    print(f"P: {question}")
    print(f"R: {response.output_text}")
    print(f"   ({tokens} tokens)\n")

print(f"Total: {total_tokens} tokens consumidos")

Pontos-chave

  • Uma chamada básica requer apenas model e input
  • response.output_text fornece o texto da resposta
  • response.usage detalha o consumo de tokens
  • temperature controla a criatividade (0.0 = factual, 1.0 = criativo)
  • instructions substitui a mensagem de sistema das Completions de Chat
  • Trate sempre os erros com blocos try/except