> ## 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. # Responses > The Gloo AI Responses API — OpenAI-compatible, multimodal, values-aligned, and guarded by default. The recommended way to build on Gloo AI. The **Responses API** (`POST /ai/v2/responses`) is the recommended way to build on Gloo AI. It pairs the OpenAI-compatible Responses request shape — one typed `input`/`output[]` format for text, vision, reasoning, tool use, and native image generation — with Gloo's full safety and values pipeline: the same guardrails, values-aligned `tradition` responses, and output moderation that power [Completions](/api-guides/completions-v2). **New to Gloo AI? Start here.** The Responses API is the standard surface going forward. If you already use [Completions V2](/api-guides/completions-v2), it remains fully supported — see [Moving from Completions to Responses](#moving-from-completions-to-responses). ## Why the Responses API * **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` and call `responses.create`. * **Guarded by default.** Every request runs the same pipeline as `/ai/v2/chat/completions` — guardrails, blocked-content handling, ministry-aware prompting, and output moderation — with no extra configuration. * **Values-aligned.** The `tradition` parameter customizes responses to theological perspectives, exactly as on Completions. * **Built for multimodal.** Image input (vision) and image generation are first-class: the same endpoint that answers a text prompt can read an image or return a generated one, using the same `input` array and typed `output[]` items. * **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. If you are starting a new integration, build on the Responses API. ## Which API should I use? | Use case | Recommended endpoint | | :-------------------------------------------------- | :------------------------------------------------------------------------ | | New integration with OpenAI-compatible tooling | **Responses** (this page) | | Vision (image input) or image generation | **Responses** (this page) | | Values-aligned (`tradition`) responses | **Responses** (this page) or [Completions V2](/api-guides/completions-v2) | | Intelligent auto-routing / `model_family` selection | [Completions V2](/api-guides/completions-v2) | | Grounded / RAG completions with source attribution | [Grounded Completions](/api-guides/grounded-completions) | ## Endpoint **URL:** `https://platform.ai.gloo.com/ai/v2/responses` **Operation:** `POST` **Responses v1 is deprecated.** `POST /ai/v1/responses` is deprecated in favor of v2. It keeps working, but v2 uses the identical request/response shape and adds more features — guardrails, values-aligned `tradition` responses, and output moderation. Migrating is a one-line change: point your requests at `/ai/v2/responses`. One exception: **grounded responses** (RAG with source attribution) remain served by the v1 family at `POST /ai/v1/grounded/responses` — there is no v2 grounded endpoint yet. ```bash theme={null} curl -X POST 'https://platform.ai.gloo.com/ai/v2/responses' \ -H 'Authorization: Bearer ${GLOO_API_KEY}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gloo-anthropic-claude-sonnet-4.6", "tradition": "evangelical", "input": [ { "role": "user", "content": "How can our small group support a grieving member?" } ] }' ``` 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. | | `tradition` | `tradition` | Identical semantics. | | Parameter | Type | Required? | Description | | :-------------------- | :--------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | Yes | Gloo model ID (e.g. `gloo-anthropic-claude-sonnet-4.6`). Pinned-model only — auto-routing and `model_family` are [Completions V2](/api-guides/completions-v2) features. | | `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. | | `tradition` | string | No | `"evangelical"`, `"catholic"`, or `"mainline"`, or omit for a general Christian perspective. Invalid values are ignored gracefully. | | `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. | | `parallel_tool_calls` | boolean | No | Allow multiple tool calls per turn. | | `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. | 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. ## Guardrails and values Requests dispatch through the same pipeline as Completions V2, so guardrail behavior is identical: * **Values-aligned static responses.** When guardrails intervene with a curated, tradition-appropriate answer, it comes back as a *normal* Responses payload — a `message` item in `output[]` carrying the static text. Your client needs no special handling. * **Hard blocks.** Requests that guardrails reject outright return the same `403` error as `/ai/v2/chat/completions`. * **Output moderation.** Model text output passes through Gloo's moderation layer before it reaches you. ## Response format Responses return a typed `output[]` array. Each item has a `type`; a normal text answer arrives as a `message` 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": "Grief support starts with presence..." } ] } ], "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.created data: {"type":"response.created","response":{"id":"resp_a1b2c3","object":"response",...}} event: response.output_text.delta data: {"type":"response.output_text.delta","item_id":"msg_...","delta":"Grief "} event: response.output_text.done data: {"type":"response.output_text.done","item_id":"msg_...","text":"Grief support starts..."} event: response.completed data: {"type":"response.completed","response":{"id":"resp_a1b2c3",...,"output":[...],"usage":{...}}} ``` Key event types to handle: * `response.created` — emitted once at the start of the response. * `response.output_text.delta` / `response.output_text.done` — incremental text tokens for a `message` item. * `response.output_item.added` / `response.output_item.done` — emitted for typed items in `output[]` (including `function_call`). * `response.completed` — emitted once when the response is finished; the final payload includes the full `output[]` array and `usage`. Token usage is always included on streams — you don't need to request it. * Error events — surfaced as event types prefixed with `error.` (e.g. `error`); treat any unknown event as terminal and close the stream. Streams can fail after the response has started — see [Handling Streaming Failures](/best-practices/completions-streaming-failures) for retry, continuation, and partial-output guidance. ## 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/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/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......" } ], "usage": { "input_tokens": 14, "output_tokens": 1290, "total_tokens": 1304 } } ``` Decode the base64 `result` to get the image bytes. #### 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 model id (exactly as on OpenAI's own API). 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/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/chat/completions`) is **fully supported and backwards-compatible** — existing integrations continue to work unchanged, and it remains the home of intelligent auto-routing, `model_family` selection, and [grounded completions](/api-guides/grounded-completions). The Responses API is the recommended surface for new work because it standardizes on the OpenAI-compatible Responses shape while keeping the same guarded pipeline. The migration is mostly a rename: | Completions V2 | Responses API | | :----------------------------------- | :----------------------- | | `POST /ai/v2/chat/completions` | `POST /ai/v2/responses` | | `messages` | `input` | | `system` role message | `instructions` | | `max_tokens` | `max_output_tokens` | | `tradition` | `tradition` (unchanged) | | `choices[].message.content` (string) | `output[]` (typed items) | ```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" } ], "tradition": "evangelical", "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" } ], "tradition": "evangelical", "max_output_tokens": 256 } ``` Auto-routing, `model_family`, and grounded completions remain [Completions V2](/api-guides/completions-v2) capabilities. If you need them, stay on Completions — everything else can move to Responses today. ## Related Documentation * [Supported Models](/api-guides/supported-models) — model IDs, capabilities, and live pricing * [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, `model_family`, and grounded completions