Skip to main content
This guide builds four working examples on the Gloo AI Responses API: a basic guarded response with a theological tradition, instructions with multi-turn input, streaming, and vision (image input). Want the concepts first? Read the Concepts guide. AI 104 in the AI Learning Center also covers conversations, streaming and images.
Why Responses? The Responses API is a flexible way to build on Gloo AI. It uses the OpenAI-compatible Responses request shape and is guarded by default — every request runs the same guardrails, values-aligned tradition responses, and output moderation that power Completions V2, with no extra configuration.

What you’ll build

Four working requests on the guarded Responses API, one per step:

Prerequisites

You need:

The Responses API at a glance

The Responses API Guide covers every field. All requests go to a single guarded endpoint: POST /ai/v2/guarded/responses

Key Request Fields

Answers come back as a typed output[] array. See Step 1’s “Understanding the response” for the full shape and how to extract the text.

Guardrail Behavior

Values-aligned static answers arrive as normal messages. When guardrails intervene with a curated, tradition-appropriate answer, it comes back as a regular message item in output[] — identical shape to a model answer. Extract the text as usual. Hard blocks return 403. Requests that guardrails reject outright return an HTTP 403:
A 403 isn’t transient: adjust the request content instead of retrying. See Handle what guarded sends back. Model text output also passes through Gloo’s output-moderation layer before it reaches you — for the full pipeline, see Guardrails and values in the Responses API Guide.

Moving from Completions

If you already use Completions V2, the migration is mostly a rename:
Auto-routing and model_family selection remain Completions V2 features; Responses needs an exact model on every request.

Step 1: Send a guarded response with a tradition

Send a plain-string input and a tradition to get a values-aligned answer:
Claude Opus 5.5 is a reasoning model: its thinking and its answer share max_output_tokens, and Responses sends the limit as you set it. These examples set 8,192 so there’s room for both. See Set your output limit for reasoning models for sizing.

Understanding the Response

The answer comes back as a typed output[] array — a message item whose content[] holds output_text parts:
To extract the text, walk output[] for message items and join their output_text parts — the cookbook samples do exactly this in an extractText helper.
Running the full sample prints one block per example, then the final banner:

Step 2: Add instructions and multi-turn input

Use instructions for system-level guidance and pass the conversation as an input array. The history alternates user → assistant → user (three turns), so the model continues the conversation with full context:
The reply arrives as the same message item in output[] shown in Step 1, continuing the conversation.Running the full sample prints the second block:

Step 3: Stream the response (SSE)

Set "stream": true to receive the response as Server-Sent Events.

Understanding the stream

The key event types in the stream, and what to do with each: On the wire, each event is an event: line followed by a data: line:
The live API sends flattened payloads: each data: line is the event object itself (its type matches the event: line), with no nested response wrapper. The response.completed payload carries usage at the top level and does not include the output[] array — the full text arrives via response.output_text.done. The snippets below accept both the flattened shape and the nested shape so they work with either.
When you run the full sample, the deltas print live as they arrive. After the stream completes, the runner prints the model, the streamed-text length with a preview, and the usage from response.completed:
Streams can fail after the response has started — a dropped connection mid-stream means partial output. See Handling Streaming Failures for retry, continuation, and partial-output guidance.

Step 4: Send an image (vision)

Vision uses the same endpoint — pass typed content parts (input_text + input_image) in the content of an input item. Use a vision-capable model such as gloo-google-gemini-3.8-flash; every Claude, Gemini and Grok chat model reads images, as does every OpenAI GPT model except the open-weight GPT OSS models. To send a photo from a file or an upload as base64, follow Understand Images with Claude.
The reply arrives as a normal message item in output[] — for the cat photo above, the answer identifies the animal:
Running the full sample prints the fourth block:

Complete code

View Complete Code

Clone or browse the complete working examples for all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java) with setup instructions.

What’s Included

Each language implementation provides:
  • auth — Shared API key configuration
  • config — Centralized configuration (endpoint, env vars)
  • Runner per example — Basic guarded response, instructions + multi-turn, streaming, and vision, plus a final banner
  • Env helper — Ignores unset .env placeholders
  • post helper — Shared request helper that annotates 403s with “(guardrails hard-blocked this request)”
  • extractText helper — Reusable helper for pulling text out of output[]
Set up your credentials first:
Then run per language:
Each runner prints a block per example (model used, first ~100 characters of the response, token usage, and a ✓ pass line), then the final banner:
The snippets in this tutorial are simplified to be self-contained. The cookbook samples add the env, post and extractText helpers listed above; the prompts, field names, and endpoint are identical.

Troubleshooting

Your .env file is missing or doesn’t contain GLOO_API_KEY. Create one in the language’s directory (see Complete code), or export the variable in your shell for Go and Java.
Guardrails hard-blocked the request. The 403 body includes a content_policy_violation detail — rephrase the request rather than retrying. See Guardrail behavior.
The model isn’t vision-capable. Vision requires a multimodal model like gloo-google-gemini-3.8-flash — sending image parts to a text-only model fails. Check Supported Models for capabilities.
The API fetches image_url server-side, so the URL must be publicly reachable. Test it in a browser or curl -I <url>. Private or expiring URLs fail; use a public URL or a base64 data: URI.
The payloads are flattened — the data: line is the event object itself, not { "response": {...} }. Match on the event: line, handle response.output_text.delta/done and response.completed, and ignore other response.* lifecycle events. Treating unknown events as terminal (and closing the stream) is the safe default.

Next steps

For auto-routing and model_family selection, see the Completions V2 Guide; for all available models, see Supported Model IDs. To learn the concepts behind these, see Tools and MCP and How RAG Actually Works in the Learning Center.

Responses API Guide

Full API documentation.

Tool Use

Function calling with Responses.

Grounded Responses

RAG with source attribution.

Direct Responses

The unguarded direct endpoint.