Responses

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.

New to Gloo AI? Start here. The Responses API is the standard surface going forward. If you already use Completions V2, it remains fully supported — see 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
Intelligent auto-routing / `model_family` selection	Completions V2
Grounded / RAG completions with source attribution	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.

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.

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 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.
`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.
`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.

{
  "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:

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 for retry, continuation, and partial-output guidance.

Multimodal

Image input (vision)

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

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.

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:

{
  "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.

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:

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 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 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.
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 and 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 page.

Moving from Completions to Responses

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. 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)

// 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
}

// 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 capabilities. If you need them, stay on Completions — everything else can move to Responses today.

Supported Models — model IDs, capabilities, and live pricing
Prompt Caching — reduce cost and latency with cached prompt prefixes
Tool Use — function calling
Completions V2 — routing, model_family, and grounded completions

Get Started

Completions & Responses

Content

Organization & Billing

GlooCode

Learn More

External

Legacy

Why the Responses API

Which API should I use?

Endpoint

Request format

Guardrails and values

Response format

Streaming

Multimodal

Image input (vision)

Image generation

OpenAI: image generation via the image_generation tool

Pricing & token spend

Supported models

Moving from Completions to Responses

​Why the Responses API

​Which API should I use?

​Endpoint

​Request format

​Guardrails and values

​Response format

​Streaming

​Multimodal

​Image input (vision)

​Image generation

​OpenAI: image generation via the image_generation tool

​Pricing & token spend

​Supported models

​Moving from Completions to Responses

​Related Documentation

Why the Responses API

Which API should I use?

Endpoint

Request format

Guardrails and values

Response format

Streaming

Multimodal

Image input (vision)

Image generation

OpenAI: image generation via the image_generation tool

Pricing & token spend

Supported models

Moving from Completions to Responses

Related Documentation