# GPT-5.6 Terra API

> GPT-5.6 — frontier reasoning and generation through one API.

- **Provider**: OpenAI
- **Model id**: `gpt-5-6-terra`
- **Modality**: text
- **Price**: 54.88–329.28 credits

## Overview

GPT-5.6 Terra is called in ONE step: POST your request and the answer comes back in the same response, in `text`. There is no task to poll.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `gpt-5-6-terra` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Text value (example: Compare two ways to store user files for a small API: object storage with signed URLs, versus streaming through our own server. For each, give the failure mode… — full value in the request example) |
| memory | boolean | No | Automatically append previous messages to maintain multi-turn context. May increase token usage. (true/false) (default: false) |
| web_search | boolean | No | Web search feeds the results back as input tokens, so a searched turn typically costs many times a normal turn (measured: 18–87×). Billed per token as usual — nothing extra per search. (true/false) (default: true) |
| reasoning_effort | string | No | Control reasoning depth: Low for faster responses, High for deeper analysis (options: Low \| Medium \| High \| XHigh) (default: Medium) |
| stream | boolean | No | Send true to receive the reply as an event stream (Content-Type: text/event-stream). Omit it and you get a single JSON response — streaming is opt-in on this endpoint. (true/false) (example: true) |
| images | string[] | No | Up to 4 images per message — JPEG, PNG, GIF or WebP, 5 MB each. Send each one as a data: URL or an https URL. Images are billed as input tokens. (image URL) |
| system | string | No | System instruction for the model. Defaults to "You are GPT-5.6 Terra, developed by OpenAI." when omitted. |
| messages | array | No | A conversation instead of a single `prompt`: up to 20 objects of { "role", "content" }, where role is user, assistant or system. Send `prompt` or `messages`, not both. Do not flatten a conversation into one prompt with "User:" / "Assistant:" labels — the model reads that as a single message, and a model using web search then searches for the whole block instead of your question. |

### Request example

```json
{
  "modelId": "gpt-5-6-terra",
  "input": {
    "prompt": "Compare two ways to store user files for a small API: object storage with signed URLs, versus streaming through our own server. For each, give the failure mode that bites first at scale, the cost that grows fastest, and one thing that is hard to change later. Then pick one for a service serving 10,000 files a day and say what would change your mind. Under 250 words.",
    "memory": false,
    "web_search": true,
    "reasoning_effort": "Medium",
    "stream": true,
    "images": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAFklEQVR4nGP8z4AATAxIHFQeMg8OAgB1yQIDpk8YwwAAAABJRU5ErkJggg=="
    ]
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 24
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=gpt-5-6-terra`

When `state` is `success`, the output is in `resultUrls`: `{ "text": "…" }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |
| 400 · too_many_images | More than 4 image(s) attached to one message |
| 400 · image_too_large | An attached image is over the 5 MB per-image limit |
| 400 · image_format_unsupported | Unsupported image format — accepted: image/jpeg, image/png, image/gif, image/webp (read from the file's own bytes, not the declared type) |
| 400 · image_unreadable | An attached image, or its pixel size, could not be read |
| 400 · capability_not_supported | A capability was requested (e.g. `web_search: true`) that this model does not offer — refused, nothing charged, rather than answered without it |
| 502 · image_not_received | The model answered that it did not receive the attached image — the reply is not usable, so nothing is charged. Retry |
| 400 · unknown_image_field | Images were sent under a different key (input_urls, image_urls, imageUrl …). This model takes them as `images` |
| 400 · image_placement_unsupported | An image is attached to a message that is not sent to the model (a system message, an assistant message, or a turn older than the last 20). Attach images to a user message in the current turn — they are refused rather than dropped |