How to Use GPT-6.1 Terra: API Setup, Reasoning Effort, and Tool Calling

The shortest path to GPT-6.1 Terra is the Responses API. A useful implementation, however, needs more than a model ID. It should define the task, select a reasoning level, supply images at an appropriate detail setting, validate the output, and restrict any tools that can change external state.

This tutorial uses current OpenAI API conventions and the model ID gpt-6.1-terra. It focuses on a visual-review workflow because that matches Terra's official positioning.

Before You Start

You need an OpenAI API project with access to GPT-6.1 Terra, an API key stored outside source code, and a current OpenAI SDK. The model page currently lists no API support for the Free tier, so verify access in your project rather than assuming that ChatGPT plan access and API access are the same.

Install the Python SDK:

pip install --upgrade openai

Set OPENAI_API_KEY through your shell or secret manager. Do not paste a production key into a script, screenshot, repository, or client-side application.

Make a Basic Text Request

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "medium"},
    instructions=(
        "Write concise production notes. Separate visible evidence "
        "from inference, and state when the supplied material is insufficient."
    ),
    input="Turn this review note into a clear five-item action list: ...",
)

print(response.output_text)

OpenAI recommends the Responses API for direct model requests and reasoning models. The instructions value applies to the current request. Put stable behavioral guidance there and keep the user input focused on the specific job.

Analyze an Image

Terra accepts image input and returns text. A Responses request can include text and an image URL:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "medium"},
    input=[{
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": (
                    "Review this campaign image. Report only visible issues "
                    "with cropping, text placement, contrast, and logo safety. "
                    "For each issue, cite the visible region and propose a fix."
                ),
            },
            {
                "type": "input_image",
                "image_url": "https://example.com/asset.jpg",
                "detail": "high",
            },
        ],
    }],
)

print(response.output_text)

Supported image formats include PNG, JPEG, WEBP, and non-animated GIF. OpenAI's vision guide also supports Base64 data URLs. Images consume tokens, so use a resolution and detail level justified by the task. For dense or coordinate-sensitive screens, original can be appropriate when supported; for an initial coarse review, low may be enough. Verify the current model-specific sizing table before standardizing a setting.

Select Reasoning Effort Deliberately

Terra supports none, low, medium, high, xhigh, and max; medium is the default. More effort can increase quality on difficult tasks, but it can also increase latency and token use.

A sensible evaluation ladder is:

• none: simple extraction or classification where multi-step reasoning adds little value.
• low: routine review, drafting, or bounded tool use.
• medium: mixed evidence, judgment, or multi-step work; this is the default.
• high: difficult visual discrepancies, planning, or complex exception handling.
• xhigh and max: use only when evaluations show a material gain for a high-value task.

Do not raise effort automatically whenever an answer fails. First inspect the prompt, evidence, image quality, output contract, and validation logic.

Request Structured Output

Production systems should not parse arbitrary prose when a known schema will do. Terra supports Structured Outputs. A visual-QA schema might require an array of issues with category, evidence, severity, and recommendation.

The exact SDK helper syntax can change, so follow the current Structured Outputs guide for your language. Regardless of syntax, validate the returned object and define what the application should do when required evidence is missing. A valid JSON shape can still contain an incorrect observation.

Add Tools Through the Responses API

Terra's listed Responses API tools include web search, file search, image generation, code interpreter, hosted shell, computer use, MCP, and others. Expose only the tools the task needs.

For computer use, your application must run or connect an execution environment, perform allowed actions, return screenshots, and preserve the session as needed. OpenAI's safety guidance recommends:

• An isolated browser or virtual machine.
• An allowlist of sites and actions.
• No credentials in page text or screenshots when avoidable.
• User approval before purchases, data transmission, deletion, or other consequential actions.
• Step, time, and cost limits.
• Verification of the saved result rather than trusting the model's summary.

Page content is untrusted. A web page cannot grant new authority or override the user's instruction.

A Reliable Visual-Review Loop

A robust implementation separates observation from action:

1. Send the image and a narrow review rubric.
2. Ask for visible evidence for every finding.
3. Validate the response schema.
4. Route high-severity or low-evidence findings to a person.
5. If changes are permitted, expose only the necessary editing or computer tools.
6. Capture the resulting state and run a verification pass.
7. Save the original, proposed action, approval, output, and reviewer decision.

For creative work, Terra can turn a storyboard review into a structured revision brief. A creator may then apply that approved brief in a separate image, animation, or story-production tool.

Common Implementation Errors

Sending a video file directly

Terra does not list native video input. Extract representative frames and, if needed, provide a transcript or shot metadata. State clearly that the analysis is based on those materials.

Allowing free-form tool use

Giving a model broad computer access creates unnecessary risk. Restrict tools, domains, actions, and data. Require approval at the point of consequence.

Treating output as ground truth

Vision models can miss small details or infer unsupported relationships. Use known test cases and human review where errors matter.

Ignoring long-context pricing

Terra's context window is 1.05 million tokens, but prompts above 272,000 input tokens receive higher rates for the full request. Retrieve only relevant material when possible.

Frequently Asked Questions

Can I use Chat Completions with GPT-6.1 Terra?

The model page lists Chat Completions as an endpoint, but states that tool calling requires the Responses API. For a new tool-using implementation, Responses is the appropriate default.

Does Terra support fine-tuning?

The current model page lists fine-tuning as unsupported. Use clear instructions, retrieval, examples, schemas, and evaluations instead of building a plan around fine-tuning.

How should I test an upgrade to higher reasoning effort?

Run the same representative evaluation set at two or more effort levels. Compare accepted results, latency, token usage, and failure categories. Do not judge from one impressive example.

Implementation Summary

Use gpt-6.1-terra through the Responses API, start at medium effort, give the model only the evidence and tools it needs, and validate both structure and substance. The quality of the surrounding harness—permissions, evaluation, verification, and logging—matters as much as the model selection.