> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Responses

> POST /ai/v2/direct/responses — the Responses request shape sent straight to the model you name, with no guardrails, moderation, values-alignment or routing in between.

**Direct Responses** is the [direct endpoint](/api-guides/endpoint-types) for the Responses format: `POST /ai/v2/direct/responses` sends your request straight to the `model` you name. It exposes the entire Gloo AI model catalog through a single endpoint — text, vision, reasoning, tool use, and native image generation — with one request and response shape that works the same across every provider.

It takes the **same request body** as the guarded [Responses](/api-guides/responses) endpoint; the difference is what runs around it. Nothing here applies guardrails, output moderation, values-alignment (`tradition`), `model_family` selection or intelligent routing. Choose this when your application owns its own safety and prompting; choose guarded [Responses](/api-guides/responses) — the recommended default — when it should inherit Gloo's. See [Which endpoint should I use?](/api-guides/endpoint-types#which-endpoint-should-i-use) for the full comparison across all three endpoint families.

<Note>
  **New to Gloo AI?** Start on the guarded [Responses](/api-guides/responses) endpoint — same request shape, with Gloo's guardrails and values-alignment applied — and come here only if you need the unprocessed path. If you already use [Completions V2](/api-guides/completions-v2), it remains fully supported and backwards-compatible — see [Moving from Completions to Responses](#moving-from-completions-to-responses).
</Note>

## Why the Responses API

The Responses API offers a more capable, forward-looking request shape that the broader ecosystem is standardizing on:

* **One shape for every modality.** Text, image input (vision), and image generation all use the same `input` array and the same typed `output` array — no separate endpoints or bespoke payloads per capability.
* **OpenAI-compatible.** The request and response formats mirror the OpenAI Responses API, so existing tooling, SDKs, and mental models carry over directly. Point your base URL at `https://platform.ai.gloo.com/ai/v2/direct` and go.
* **Typed, structured output.** Responses come back as an `output[]` array of typed items (`message`, `image_generation_call`, reasoning, tool calls) instead of a single opaque `choices[].message.content` string — easier to parse, and extensible as new item types arrive.
* **Built for multimodal.** Native image generation and image input are first-class, not bolted on. The same endpoint that answers a text prompt can return a generated image.

If you are starting a new integration, build on the Responses API.

## Endpoint

**URL:** `https://platform.ai.gloo.com/ai/v2/direct/responses`

**Operation:** `POST`

```bash theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/responses' \
  -H 'Authorization: Bearer ${GLOO_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "input": [
      { "role": "user", "content": "Explain prompt caching in two sentences." }
    ]
  }'
```

Authentication is identical to the rest of the platform — send your API key as a Bearer token. See [Generate API Keys](/studio/manage-api-credentials).

## Request format

The Responses API uses `input` instead of `messages`, and a few renamed fields. If you know the chat-completions format, the mapping is small:

| Responses API       | Chat Completions equivalent | Notes                                                                   |
| :------------------ | :-------------------------- | :---------------------------------------------------------------------- |
| `input`             | `messages`                  | A string, or an array of input items (`role` + `content`).              |
| `instructions`      | `system` message            | Top-level system / developer instructions.                              |
| `max_output_tokens` | `max_tokens`                | Cap on generated tokens.                                                |
| `model`             | `model`                     | A Gloo model ID — see [Supported Models](/api-guides/supported-models). |

| Parameter           | Type             | Required? | Description                                                                    |
| :------------------ | :--------------- | :-------- | :----------------------------------------------------------------------------- |
| `model`             | string           | Yes       | Gloo model ID (e.g. `gloo-anthropic-claude-sonnet-4.6`).                       |
| `input`             | string \| array  | Yes       | A plain string prompt, or an array of typed input items.                       |
| `instructions`      | string           | No        | System-level instructions applied to the request.                              |
| `max_output_tokens` | integer          | No        | Maximum number of tokens to generate.                                          |
| `temperature`       | float            | No        | Sampling temperature.                                                          |
| `top_p`             | float            | No        | Nucleus sampling.                                                              |
| `tools`             | array            | No        | Tool / function definitions. See [Tool Use](/api-guides/tool-use).             |
| `tool_choice`       | string \| object | No        | Controls tool selection.                                                       |
| `stream`            | boolean          | No        | Stream the response as SSE events (default `false`).                           |
| `reasoning`         | object           | No        | Reasoning controls (e.g. effort) for capable models.                           |
| `response_format`   | object           | No        | Structured-output / JSON schema controls.                                      |
| `prompt_cache_key`  | string           | No        | Improves cache-hit routing — see [Prompt Caching](/api-guides/prompt-caching). |
| `image_generation`  | object           | No        | Image-generation options (`quality`, `size`) for image-capable models.         |

<Info>
  Conversation state is managed client-side by passing the full `input` history on each request. The `previous_response_id` parameter (used by OpenAI's Responses API for server-side conversation chaining) is not supported.
</Info>

<Warning>
  **This is a [direct endpoint](/api-guides/endpoint-types): `/ai/v2/direct/responses` does not apply the governance layer.** Requests here call the exact `model` you specify with no additional processing. None of the following runs:

  * Input guardrails and output moderation
  * Values-alignment (`tradition`)
  * `model_family` selection and intelligent auto-routing

  **Want the same request body with those applied?** Use the guarded [Responses](/api-guides/responses) endpoint at `/ai/v2/guarded/responses` — same body, different URL. [Completions V2](/api-guides/completions-v2) and [Grounded Completions](/api-guides/grounded-completions) are guarded too, on the Chat Completions shape.

  "Direct" describes this URL, not the Responses format in general: the same format is served by the guarded endpoint above and by [Grounded Responses](/api-guides/grounded-responses), which adds retrieval-augmented (RAG) generation over your own content.
</Warning>

## Response format

Responses return a typed `output[]` array. Each item has a `type`; a normal text answer arrives as a `message` item, a generated image as an `image_generation_call` item.

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Prompt caching reuses processed prompt tokens..." }
      ]
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 38, "total_tokens": 62 }
}
```

### Streaming

Set `"stream": true` to receive the response as Server-Sent Events. Each event has an `event:` line and a `data:` line carrying a typed JSON payload:

```text theme={null}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_...","type":"message","role":"assistant"}}

event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_...","part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","delta":"Prompt "}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","delta":"caching "}

event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_...","part":{"type":"output_text","text":"Prompt caching reuses..."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_...","type":"message",...}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_a1b2c3",...,"output":[...],"usage":{...}}}
```

Key event types to handle:

* `response.output_item.added` / `response.output_item.done` — mark the start and end of each typed item in `output[]` (including `message`, `image_generation_call`, and `function_call`).
* `response.content_part.added` / `response.content_part.done` — mark the start and completion of a content part within an item. `response.content_part.done` is the signal that a message's text is complete, followed by `response.output_item.done`.
* `response.output_text.delta` — incremental text tokens for a `message` item.
* `response.function_call_arguments.delta` — incremental tool-call argument tokens for a `function_call` item.
* `response.completed` — emitted once when the response is finished; the final payload includes the full `output[]` array and `usage`.

Errors are not delivered as SSE events. They surface as an HTTP error status (or a raised exception in the SDK), so handle them on the request itself rather than watching for an `error` event in the stream.

## Multimodal

### Image input (vision)

Pass images as input items alongside text. Any vision-capable model accepts them:

```bash theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/responses' \
  -H 'Authorization: Bearer ${GLOO_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-google-gemini-3.1-pro",
    "input": [
      { "role": "user", "content": [
        { "type": "input_text", "text": "Describe this image." },
        { "type": "input_image", "image_url": "https://example.com/photo.jpg" }
      ]}
    ]
  }'
```

Images may be supplied as a remote URL or a base64 `data:` URI.

### Image generation

Image-capable models return a generated image as an `image_generation_call` output item (base64 result). Optional `image_generation` controls (`quality`, `size`) are forwarded to providers that support them.

```bash theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/responses' \
  -H 'Authorization: Bearer ${GLOO_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-google-gemini-3-pro-image",
    "input": [
      { "role": "user", "content": [
        { "type": "input_text", "text": "A watercolor painting of a lighthouse at sunset." }
      ]}
    ]
  }'
```

The generated image comes back as a typed `image_generation_call` item in `output[]`. The `result` field carries the image as a base64-encoded string:

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "model": "gloo-google-gemini-3-pro-image",
  "output": [
    {
      "type": "image_generation_call",
      "id": "ig_...",
      "status": "completed",
      "result": "iVBORw0KGgoAAAANSUhEUgAA...<truncated base64 PNG>..."
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 1290, "total_tokens": 1304 }
}
```

Decode the base64 `result` to get the image bytes. Optional `image_generation` controls (`quality`, `size`) are forwarded to providers that support them.

#### OpenAI: image generation via the image\_generation tool

OpenAI's image generation runs as an `image_generation` **tool** on a GPT-5 model — `gpt-image-1` is not a top-level Responses `model` (exactly as on OpenAI's own API, where it is an Images API model rather than a Responses one). Call a GPT-5 model and attach the tool; the model decides when to draw and can combine the image with text in the same response. The tool accepts an optional `model` field to pin its backing image model (e.g. `gpt-image-1`) plus `quality`/`size` controls:

```bash theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/responses' \
  -H 'Authorization: Bearer ${GLOO_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-openai-gpt-5-mini",
    "input": [
      { "role": "user", "content": [
        { "type": "input_text", "text": "A watercolor painting of a lighthouse at sunset." }
      ]}
    ],
    "tools": [
      { "type": "image_generation", "model": "gpt-image-1", "quality": "low" }
    ]
  }'
```

The generated image arrives as the same `image_generation_call` output item shown above (alongside any `reasoning` and `message` items from the GPT-5 model). **Image editing** works through the same mechanism: include an `input_image` part in the conversation and it becomes the tool's edit source.

See [Supported Models](/api-guides/supported-models) for which models support image input and image generation.

## Pricing & token spend

The Responses API is billed per token at each model's standard rates — there is no separate or premium price for using `/responses`. Cost is driven entirely by the `model` you select and the tokens you consume:

```
total_cost = input_tokens  × input_rate
           + cached_tokens  × cache_read_rate
           + output_tokens  × output_rate
```

* **Per-model rates.** Input and output rates vary by model. The live rates are on the [Supported Models](/api-guides/supported-models) page and programmatically on `GET /platform/v2/models`.
* **Prompt caching** reduces input cost when prompt prefixes repeat — cached tokens are billed at a discounted `cache_read` rate. See [Prompt Caching](/api-guides/prompt-caching).
* **Image generation** is billed using the image model's token accounting; check the model's rates on the models endpoint.
* A **6.5% Studio markup** applies to every token segment, consistent with the rest of the platform.

Track real spend in the [Gloo Studio billing dashboard](https://studio.ai.gloo.com/billing) and [API usage](/studio/api-usage).

## Supported models

The Responses API works across the full Gloo AI catalog — Anthropic, OpenAI, Google, and open-source families — including the multimodal and image-generation models. Use the **Model ID** as the `model` field. The complete, live list (with capabilities and pricing) is on the [Supported Models](/api-guides/supported-models) page.

## Moving from Completions to Responses

[Completions V2](/api-guides/completions-v2) (`/ai/v2/guarded/chat/completions`) is **fully supported and backwards-compatible** — existing integrations continue to work unchanged, and it remains the home of auto-routing and `model_family` selection. Guardrails, output moderation and `tradition` have already reached the Responses shape on the guarded [Responses](/api-guides/responses) endpoint, and RAG grounding on [Grounded Responses](/api-guides/grounded-responses).

The Responses API is the recommended surface for new work because it standardizes on the OpenAI-compatible Responses shape and makes multimodal (vision + image generation) first-class. Below the URL, the migration is mostly a rename:

| Completions V2                         | Responses API                   |
| :------------------------------------- | :------------------------------ |
| `POST /ai/v2/guarded/chat/completions` | `POST /ai/v2/guarded/responses` |
| `messages`                             | `input`                         |
| `system` role message                  | `instructions`                  |
| `max_tokens`                           | `max_output_tokens`             |
| `choices[].message.content` (string)   | `output[]` (typed items)        |

<Warning>
  **The URL is the one row that is not a rename.** Completions V2 applies guardrails, output moderation and `tradition`; this page's endpoint applies none of them. `POST /ai/v2/guarded/responses` is the like-for-like destination — it keeps the governance layer while changing the request shape. Move to `POST /ai/v2/direct/responses` only if dropping that layer is a decision you are making deliberately, and the body stays identical either way.
</Warning>

```json theme={null}
// Completions V2
{
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello" }
  ],
  "max_tokens": 256
}
```

```json theme={null}
// Responses API (equivalent)
{
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "instructions": "You are a helpful assistant.",
  "input": [
    { "role": "user", "content": "Hello" }
  ],
  "max_output_tokens": 256
}
```

<Note>
  `tradition`, guardrails and output moderation are available now on the guarded [Responses](/api-guides/responses) endpoint, and grounded (RAG) responses on [Grounded Responses](/api-guides/grounded-responses). Auto-routing and `model_family` selection remain on [Completions V2](/api-guides/completions-v2), and grounding with citation metadata on [Grounded Completions](/api-guides/grounded-completions). Choose this page's direct endpoint when your application owns its own safety and prompting.
</Note>

## Related Documentation

* [Supported Models](/api-guides/supported-models) — model IDs, capabilities, and live pricing
* [Grounded Responses](/api-guides/grounded-responses) — RAG-grounded answers in the Responses API format
* [Prompt Caching](/api-guides/prompt-caching) — reduce cost and latency with cached prompt prefixes
* [Tool Use](/api-guides/tool-use) — function calling
* [Completions V2](/api-guides/completions-v2) — routing, values-alignment, and backwards-compatibility