A Sua Primeira Chamada à API
Nesta página
Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API de Respostas) oureasoning_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
modeleinput response.output_textfornece o texto da respostaresponse.usagedetalha o consumo de tokenstemperaturecontrola a criatividade (0.0 = factual, 1.0 = criativo)instructionssubstitui a mensagem de sistema das Completions de Chat- Trate sempre os erros com blocos try/except