Skip to main content
This step-by-step tutorial covers the Gloo AI Completions V2 API and its model selection options. Want the concepts first? Read the Concepts guide.
Why V2? Completions V2 lets you pin a specific model, choose a model family, or opt in to auto-routing, and supports tradition-aware responses—all while maintaining compatibility with the standard chat completions format.

What you’ll build

A small script that sends one chat request per model-selection mode, then reads the routing metadata and streams the answer:
  1. Pin a model
  2. Choose a model family
  3. Opt in to auto-routing
  4. Read the routing metadata in the response
  5. Stream the response
Completions V2 offers three ways to select the model. Provide exactly one of model, model_family, or auto_routing; they are mutually exclusive.

Prerequisites

You need:

Step 1: Pin a model

Pin a specific model for full control and consistent behavior across calls:
Claude Opus 5.5 is a reasoning model: its thinking and its answer share max_tokens. These examples set 8,192 so there’s room for both. See Set your output limit for reasoning models for sizing.
See the Supported Model IDs page for all available models.

Step 2: Choose a model family

Specify a provider family and let Gloo pick the model within that family:
Available model families: openai, anthropic, google, open source

Step 3: Opt in to auto-routing

Let Gloo select the model for each request:
With auto-routing, Gloo may select a different model from one call to the next. Avoid it when you need reproducible output or consistent tool-calling behavior; pin a model instead.

Step 4: Read the routing metadata

V2 responses include additional routing metadata:
Key metadata fields:
  • routing_mechanism: How the model was selected (auto_routing, model_family, or direct_model_selection)
  • routing_tier and routing_confidence: Returned when you opt in to auto-routing. routing_tier is the complexity tier Gloo determined (tier_1, tier_2, tier_3) and routing_confidence is the confidence score for that routing decision (0.0-1.0)
  • tradition: The theological perspective applied (if specified)

Step 5: Stream the response

Enable streaming for real-time responses:

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.
These examples combine all three model selection options into one runnable script per language. First set your environment variables in an .env file:
Or export them in your shell for Go and Java:

Troubleshooting

Cause: The request sent more than one of model, model_family and auto_routing, or none of them.Solution: Send exactly one. See Step 1, Step 2 and Step 3.
Cause: The request body has no messages array.Solution: Send messages with at least one user message.
Cause: The API key is missing, wrong or revoked.Solution: Check the key and the Authorization: Bearer header. See the Authentication Tutorial.
See Completions V2 errors for every status code, its cause and whether to retry.

Next steps

New to function calling? Read Tools and MCP.

Completions V2 Guide

Full API documentation.

Tool Use

Function calling with completions.

Supported Model IDs

All available models.

Build with Direct Responses

Multi-turn conversations in the Responses format.