# How to use GPT-6.1 Terra, OpenAI's new fast vision model

> Call GPT-6.1 Terra from the OpenAI Responses API to read an image, set a reasoning effort, and get structured JSON back.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-10-27 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/gpt-6-1-terra/

OpenAI released **GPT-6.1 Terra** on October 26, 2026. It's the fast, efficient model of the GPT-6 family, built for visual reasoning, computer use and clear writing.

The price is what caught my eye. It costs $1 per million input tokens and $5 per million output tokens. OpenAI says that's 50% lower than both GPT-5.6 Terra and GPT-6.1 Sol.

Here's what you get:

- a 1,050,000 token context window (up to 922,000 input tokens)
- up to 128,000 output tokens
- text and image input, text output
- a June 1, 2026 knowledge cutoff

In ChatGPT, Terra is available to Plus, Pro, Enterprise and Edu users in ChatGPT Work and Codex. In this tutorial we'll use it from the API.

## Your first request

Install the official SDK:

```bash
npm install openai
```

Then set your API key:

```bash
export OPENAI_API_KEY=sk-...
```

The model ID is `gpt-6.1-terra`. Create a `terra.mjs` file and call it with the Responses API:

```js
import OpenAI from 'openai'

const openai = new OpenAI()

const response = await openai.responses.create({
  model: 'gpt-6.1-terra',
  input: 'Write a one-line commit message for a fix to a broken pagination link'
})

console.log(response.output_text)
```

Run it:

```bash
node terra.mjs
```

## Pick a reasoning effort

Terra supports six reasoning effort values: `none`, `low`, `medium` (the default), `high`, `xhigh` and `max`.

Notice that `none` is there. GPT-6 Astra and GPT-6.1 Sol don't support it, Terra does. Use it for quick tasks where you want the fastest answer:

```js
const response = await openai.responses.create({
  model: 'gpt-6.1-terra',
  reasoning: { effort: 'none' },
  input: 'Translate "Il negozio apre alle 9" to English'
})
```

OpenAI's advice is to start with `medium` and go up only if the better quality is worth the extra time and tokens.

> Be careful with sampling parameters. When reasoning effort is not `none`, you need to remove `temperature`, `top_p` and `top_logprobs` from your request.

## Read an image

Vision is where Terra shines. OpenAI suggests using it to match product photos to catalog entries, interpret technical drawings, or read documents like invoices.

You pass an image as an `input_image` content item. Here we read a local file and send it as a Base64 data URL:

```js
import fs from 'fs'
import OpenAI from 'openai'

const openai = new OpenAI()

const image = fs.readFileSync('/Users/flavio/invoice.png', 'base64')

const response = await openai.responses.create({
  model: 'gpt-6.1-terra',
  input: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'Who sent this invoice, and what is the total?' },
        { type: 'input_image', image_url: `data:image/png;base64,${image}` }
      ]
    }
  ]
})

console.log(response.output_text)
```

You can also pass a public image URL in `image_url`, or a `file_id` from the Files API.

## Get structured data out of it

Reading an invoice is nice. Getting JSON you can save to a database is better.

Add a JSON schema in `text.format` and Terra returns data that matches it:

```mermaid
flowchart TD
  accTitle: Read an invoice with GPT-6.1 Terra
  accDescr: Your app sends text and an image to the Responses API with model gpt-6.1-terra, an optional reasoning effort and a JSON schema, and gets structured JSON back.
  App["Your app"] --> Text["Text and image"]
  Text --> API["Responses API"]
  Model["gpt-6.1-terra"] --> API
  Effort["Reasoning effort"] --> API
  Schema["JSON schema"] --> API
  API --> JSON["Structured JSON"]
```

```js
const response = await openai.responses.create({
  model: 'gpt-6.1-terra',
  input: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'Extract the invoice details' },
        { type: 'input_image', image_url: `data:image/png;base64,${image}` }
      ]
    }
  ],
  text: {
    format: {
      type: 'json_schema',
      name: 'invoice',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          vendor: { type: 'string' },
          date: { type: 'string' },
          total: { type: 'number' },
          currency: { type: 'string' }
        },
        required: ['vendor', 'date', 'total', 'currency'],
        additionalProperties: false
      }
    }
  }
})

const invoice = JSON.parse(response.output_text)
console.log(invoice.total)
```

This is the kind of high-volume job OpenAI built Terra for: reading incoming invoices and entering them into accounting software.

## Tools need the Responses API

Terra works with Chat Completions too, but tool calling requires the Responses API.

In Responses it supports function calling plus the hosted tools: `web_search`, `file_search`, `code_interpreter`, `computer_use`, `mcp`, `tool_search`, `image_generation`, `hosted_shell`, `apply_patch` and `skills`.

Here's a web search call:

```js
const response = await openai.responses.create({
  model: 'gpt-6.1-terra',
  tools: [{ type: 'web_search' }],
  input: 'What changed in the latest Node.js LTS release?'
})

console.log(response.output_text)
```

## What it costs

Standard pricing, per million tokens:

| | Price |
| --- | --- |
| Input | $1 |
| Cached input | $0.05 |
| Cache writes (30 minutes) | $1.25 |
| Cache writes (12 hours) | $2.50 |
| Output | $5 |

A few things change the bill. Prompts over 272K input tokens cost 2x on input and cache and 1.5x on output, for the whole request. Batch and Flex are 50% cheaper. Fast mode costs 2x.

## When to use it

OpenAI says Terra scored 15 percentage points higher than GPT-5.6 Terra on its Agents' Last Exam computer use benchmark, at medium effort. On Terminal-Bench 4.0 at max effort it solves 50.3% of tasks, up from 21.5%.

For the most complex coding tasks, OpenAI still recommends GPT-6.1 Sol or GPT-6 Astra. My advice is to use Terra for vision, document extraction, computer use and writing, where its speed and price make the biggest difference.

If you're migrating from GPT-5.6 Terra, run both models on the same images and workflows, at the same reasoning effort, before you switch.

## Sources

- [Introducing GPT-6.1 Terra](https://openai.com/index/introducing-gpt-6-1-terra/)
- [GPT-6.1 Terra model page](https://developers.openai.com/api/docs/models/gpt-6.1-terra)
- [Using GPT-6 guide](https://developers.openai.com/api/docs/guides/latest-model)
- [Images and vision guide](https://developers.openai.com/api/docs/guides/images-vision)
- [OpenAI API changelog](https://developers.openai.com/api/docs/changelog)
- [OpenAI API pricing](https://developers.openai.com/api/docs/pricing)