API Reference¶

Continuum Router exposes an OpenAI-compatible API with additional administrative endpoints for monitoring and management. This document covers all available endpoints, request/response formats, and error handling.

Table of Contents¶

• Overview
• Authentication
• Core API Endpoints
  • Health Check
  • Readiness Check
  • Version
  • Caller Quota
  • List Models
  • List Models with Metadata
  • Proxy a Backend Model List
  • Force-Refresh Models
  • Get Single Model
  • Chat Completions
    • Client Provider Preferences
  • Responses API
  • Retrieve, Delete, or Cancel a Stored Response
  • Responses Compact
  • Batch API
  • Image Generation
  • Image Edit (Inpainting)
  • Image Variations
  • Audio Transcriptions & Translations
  • Text Completions
  • Embeddings
  • Rerank
  • Moderations
  • Tokenize and Detokenize
  • Decisions (System One)
  • Sparse Embeddings
  • Files API
  • File Resolution in Chat Completions
• Anthropic Native API
  • Messages API
  • Token Counting
  • Models List
  • Claude Code Compatibility
• Admin API
• Admin REST API reference
• Error Handling
• Rate Limiting
• Streaming
• Examples

Overview¶

Base URL¶

http://localhost:8080

Content Type¶

All requests and responses use application/json unless otherwise specified.

OpenAI Compatibility¶

Continuum Router provides OpenAI-compatible API surfaces for: - Chat completions with streaming - Text completions - Embeddings - Reranking (Cohere-compatible /v1/rerank) - Moderations (/v1/moderations, classified by the configured guardrails) - System One decisions (/v1/decisions, alias /v1/systemone) - Sparse embeddings (TEI/Jina-compatible /embed_sparse) - Image generation - Image editing/inpainting - Image variations - Files API (upload, list, retrieve, delete) - File resolution in chat completions (image_file references) - Model listing - Error response formats

Choosing a Backend with x-backend¶

Several backends can serve the same model id. /v1/models collapses them into one aggregated entry whose backends array lists every backend name serving that id, and by default the router load-balances across them.

Send the optional x-backend request header to name the backend you want:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-backend: provider-openai-a1b2c3d4" \
  -d '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}]}'

Where it applies¶

The router honors x-backend across all model-routed inference endpoints (both streaming and non-streaming):

• /v1/chat/completions, /v1/completions, and /v1/responses
• /anthropic/v1/messages and /anthropic/v1/messages/count_tokens (and their root-level aliases /v1/messages and /v1/messages/count_tokens)
• /v1/embeddings, /v1/rerank, and /embed_sparse
• /tokenize and /detokenize (and their /v1 aliases)
• /v1/images/generations, /v1/images/edits, and /v1/images/variations
• /v1/audio/transcriptions, /v1/audio/translations, and /v1/audio/speech
• /v1/realtime WebSocket handshakes

The header is not read on these paths:

How it behaves¶

x-backend is a routing preference, never a hard pin. The named backend is used on the first attempt when all four eligibility conditions hold:

1. User-routable: The backend is enabled (enabled: true) and not internal (internal: false).
2. Allow-listed: The backend is permitted by the API key's allowed_backends list, when one is configured.
3. In the candidate pool: The backend belongs to the candidate set the request would otherwise select from:
   • Model-routed endpoints: Backends serving the requested model.
   • Nano Banana (Gemini-native) image requests: Must name a type: gemini backend (backend name and URL are not consulted), because the request is dispatched to the Gemini endpoint using the selected backend's credential; non-Gemini backends are rejected rather than borrowed.
   • OpenAI-compatible /v1/images/edits and /v1/images/variations: Capability filtering is bypassed here because the request goes directly to the named backend's URL with its own credential. Naming a visible, allow-listed backend that lacks image-edit or variation support sends the request to that backend, where it fails rather than falling back to normal selection.
4. Healthy and available: The backend is healthy and its circuit breaker admits the request.

If any check fails, the router logs a warning and falls back to normal selection. An absent, unknown, invisible, disallowed, or unhealthy backend name never fails a request; it behaves as if the header had been omitted.

• First attempt only: Retries and fallback-chain hops use normal selection, so a backend that fails mid-request still fails over.
• /v1/realtime sessions: A realtime session selects its backend once during the WebSocket handshake and binds to that backend for the lifetime of the session. There is no second selection or mid-session failover.

Confirming which backend answered¶

When a request includes x-backend, the response includes x-served-backend naming the backend that actually produced the response (including after a retry or fallback-chain hop):

curl -sS -D - -o /dev/null http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-backend: provider-openai-a1b2c3d4" \
  -d '{"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}]}' \
  | grep -i '^x-served-backend:'

• Value matches x-backend: The preference was honored.
• Value differs from x-backend: The preference was not eligible (or a retry/fallback occurred) and another backend answered.
• Header absent: Either the response did not come from an upstream backend (see table below) or the route does not read x-backend. Never interpret an absent header as confirmation that the preference applied.

Errors a backend returned¶

The router attaches x-served-backend only when the request carried x-backend and the router holds an HTTP response authored by the upstream backend itself (for example, an upstream 429 quota error). Router-authored responses and transport failures never carry the header, regardless of HTTP status code.

Detecting support (backend_preference_header_v1)¶

• Via Admin API: GET /admin/capabilities advertises backend_preference_header_v1 in its capabilities array when the router supports x-backend (see Admin REST API reference).
• Via Inference API: Send x-backend on a normal inference request and check for x-served-backend on a successful (200) non-cached response. A present x-served-backend header confirms support; comparing its value with x-backend shows whether the preference was honored.

Authentication¶

Continuum Router supports API key authentication with configurable enforcement modes.

Authentication Modes¶

The router supports two authentication modes for API endpoints:

Configuration¶

api_keys:
  # Authentication mode: "permissive" (default) or "blocking"
  mode: blocking

  # API key definitions
  api_keys:
    - key: "${API_KEY_1}"
      id: "key-production-1"
      user_id: "user-admin"
      organization_id: "org-main"
      scopes: [read, write, files, admin]

Protected Endpoints (when mode is blocking)¶

API-key middleware protects all routes in the core API router: /v1/models*, /v1/quota, /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/responses*, /v1/images/*, /v1/rerank, /v1/moderations, /v1/fine_tuning/jobs*, /v1/vector_stores*, /tokenize, /detokenize (and their /v1 aliases), /v1/decisions, /v1/systemone, /embed_sparse, /anthropic/v1/messages*, /v1/messages*, /anthropic/v1/models, and feature-gated /v1/batches* routes.

When a key has a non-empty scopes list, blocking mode also enforces the route's read or write class. write implies read, admin implies both, and files controls the separate Files API rather than satisfying /v1 read/write routes. Empty or absent scopes remains unrestricted for backward compatibility; permissive mode never rejects a request solely because an authenticated key has narrow scopes. See Security & Admin for the full route classification.

Note: Liveness, readiness, and version endpoints (/health, /health/ready, /version) are always accessible without authentication. Admin, Files, and Metrics endpoints have separate authentication mechanisms.

A key can also state prompt-capture consent with prompt_logging_consent (allowed or denied). See Where a key's consent comes from.

Making Authenticated Requests¶

Every protected route accepts the API key in either of two header forms: Authorization: Bearer <api_key> or the Anthropic-native x-api-key: <api_key>. Both forms work on every route, not only the /anthropic/* endpoints, so Anthropic SDKs and Claude Code (which set only ANTHROPIC_API_KEY and send it via x-api-key) authenticate the same way OpenAI-style clients do. When a request carries both headers, Authorization: Bearer takes precedence.

POST /v1/chat/completions HTTP/1.1
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "model": "gpt-5.6-sol",
  "messages": [{"role": "user", "content": "Hello"}]
}

POST /v1/chat/completions HTTP/1.1
x-api-key: sk-your-api-key
Content-Type: application/json

{
  "model": "gpt-5.6-sol",
  "messages": [{"role": "user", "content": "Hello"}]
}

Authentication Errors¶

When authentication fails, the API returns:

{
  "error": {
    "message": "Missing or invalid API key. Expected Authorization: Bearer <api_key> or x-api-key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status Codes:

• 401 Unauthorized: Missing or invalid API key

Core API Endpoints¶

Health Check¶

Check the health status of the router service.

GET /health

Response:

{
  "status": "ok",
  "service": "continuum-router",
  "version": "2.0.0"
}

Status Codes:

• 200: Service is healthy

Readiness Check¶

Check whether this replica has at least one active backend that is enabled and non-internal. Draining backends do not count. Upstream health and circuit-breaker state remain request-selection concerns and do not change this endpoint.

GET /health/ready

Ready response:

{
  "status": "ready",
  "service": "continuum-router",
  "routable_backend_count": 2
}

When the serving pool has no routable backend, the same body uses "status": "not_ready" and a count of 0.

Status Codes:

• 200: At least one enabled, non-internal backend is active
• 503: No enabled, non-internal backend is active

Version¶

Return the running router version.

GET /version

Response:

{
  "version": "2.0.0"
}

Status Codes:

• 200: Always returned; no authentication required

Caller Quota¶

GET /v1/quota returns the limits bound to the caller's authenticated identity and how much of each remains. It takes no parameters and no body, and it consumes no identity-bound quota, so a client can poll it without spending what it reads.

The response reports only values tied to the caller's identity. Shared fleet levels (global, per_client, per_model, per_backend), the batch dimensions, and every key id, name, user, and team are never included.

{
  "object": "quota",
  "degraded": false,
  "dimensions": [
    {"dimension": "request_rate", "unit": "requests", "limit": 20, "remaining": 17, "reset_seconds": 9, "window_seconds": null, "scope": "replica"},
    {"dimension": "token_rate", "unit": "tokens", "limit": 20000, "remaining": 18400, "reset_seconds": 6, "window_seconds": null, "scope": "fleet"},
    {"dimension": "token_budget", "unit": "tokens", "limit": 5000000, "remaining": 4100000, "reset_seconds": null, "window_seconds": 2592000, "scope": "replica"}
  ]
}

scope states how far a value holds: fleet for a value read from a store every replica shares, replica otherwise. request_rate, user_request_rate, team_request_rate, inflight, and token_budget are per replica. degraded is true when a configured shared store was unreachable and the read fell back to this replica, and also when the Redis rate-limit store fell back according to rate_limiting.redis.fallback_to_memory.

Who sees what:

An exhausted key gets 200 with remaining: 0 rather than a refusal. The shared global and per_client margins are still charged at the /v1/models cost of 0.1, so the route is metered before authentication like every other API path, but their levels are not reported. A quota response carries no x-ratelimit-* or x-continuum-ratelimit-* header.

Status Codes:

• 200: Quota read, possibly with an empty dimensions list
• 401: Missing or invalid key in blocking mode
• 403: The key's scopes lack read
• 429: The shared global or per_client margin refused the read
• 503: rate_limiting.redis.fallback_to_memory: false and the Redis store is unreachable

See Rate Limiting for the read semantics and outage behavior.

List Models¶

Retrieve the aggregated model catalog from configured, enabled backends.

GET /v1/models

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai",
      "context_length": 400000,
      "max_output_tokens": 128000,
      "pricing": {
        "input_tokens": 1.25,
        "output_tokens": 10.0
      },
      "capabilities": ["chat", "vision", "tool"],
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "logprobs", "top_logprobs"]
    },
    {
      "id": "llama2:7b",
      "object": "model",
      "created": 1677610602,
      "owned_by": "library",
      "context_length": 4096,
      "max_output_tokens": 4096,
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "top_k", "min_p", "logprobs", "top_logprobs"]
    },
    {
      "id": "anthropic/claude-haiku-4.5",
      "object": "model",
      "created": 1760547638,
      "owned_by": "anthropic",
      "context_length": 200000,
      "max_output_tokens": 64000,
      "pricing": {
        "input_tokens": 1.0,
        "output_tokens": 5.0
      },
      "capabilities": ["chat", "vision", "tool"],
      "supported_parameters": ["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "top_k", "min_p", "logprobs", "top_logprobs"]
    }
  ]
}

Status Codes:

• 200: Models retrieved successfully
• 503: All backends are unhealthy

Features:

• Model Aggregation: Combines models from configured, enabled backends
• Deduplication: Removes duplicate models across backends
• Caching: An internal 60-second hard TTL with stale-while-revalidate and request coalescing
• Outage Retention: When live discovery fails, the router keeps the last-known models for that backend in its catalog. Discovery results the router served from configuration or a fallback list (Bedrock, OAuth backends, the curated Anthropic list) never mark a backend healthy; only a live answer does.
• Routable Models Only: The list advertises a model only while the caller can request it, under these rules:
  • At least one of its backends that the caller's key may use is not marked unhealthy (a backend not yet probed or still warming up counts as usable), or
  • An enabled fallback chain is configured for the model name, so a degraded primary stays visible to clients that build model pickers from this endpoint and can still reach its fallback.
  • Otherwise the model is withheld until a backend recovers. GET /v1/models/{model} still answers 200 with available: false for it, and GET /admin/models shows it as degraded. /v1/models/extended, /v1/models/refresh, and /anthropic/v1/models apply the same rule.
• Backend Aliases: Each aliases entry in an enabled backend's model_configs is listed as its own entry, with the canonical model's backends and metadata, while alias dispatch would resolve it:
  • The alias is listed only while a user-routable backend serves the canonical model, and it leaves the list on the refresh that drops the canonical model.
  • A per-key allowed_models list must name the alias itself; the backend allow-list, internal backends, and the routable-models rule apply through the canonical model's backends.
  • A name some backend serves literally keeps its own entry, and a name a model experiment answers for is left to the experiment.
  • Aliases from model-metadata.yaml and the model_aliases section (haiku, sonnet, exact, and the others) are not listed. GET /admin/models reports each declared alias in the canonical entry's aliases.
• Vendor Attribution: When a backend sends no owned_by for a vendor/model id, as OpenRouter does for every entry, owned_by is the id's vendor namespace (anthropic/claude-haiku-4.5 reports anthropic). See Upstream vendor and metadata

• Capability Fields: Entries carry the following fields when the router knows their values, from the resolved model metadata (model-metadata.yaml, a backend's own report, or a built-in catalog entry):

  • context_length: context window in tokens.
  • max_output_tokens: maximum output tokens.
  • pricing: USD per 1M tokens.
  • capabilities: tags such as chat, vision, and tool.
  • supported_parameters: the chat request parameters the router carries to the backend, from temperature, top_p, max_tokens, presence_penalty, frequency_penalty, top_k, min_p, logprobs, and top_logprobs. It is derived from each serving backend's conversion (a local engine or raw OpenAI-compatible backend carries all of them; api.openai.com and Gemini drop top_k and min_p; Anthropic and Bedrock carry temperature, top_p, max_tokens, and top_k, or only max_tokens for a Claude model that refuses sampling fields; Bedrock Converse drops top_k as well), and a parameter is listed only when every backend serving the model carries it. A model whose capabilities list neither chat nor the text output modality an upstream catalog reports (an image or embedding model, say) has no supported_parameters. A model whose own request shape narrows the set further (for example a Claude request with reasoning, which drops temperature) is not reflected.

  When no model-metadata.yaml entry sets limits, context_length comes from the context windows the serving engines report (max_model_len or context_length on their /v1/models), folded to the minimum across backends, since any of them may serve the request. A field with no known value is omitted rather than sent as null; a model without metadata or engine reports carries only id, object, created, owned_by, and supported_parameters.

List Models with Metadata¶

Retrieve the same aggregated catalog as GET /v1/models, with the router's resolved metadata and the backends serving each model.

GET /v1/models/extended

Response:

{
  "object": "list",
  "data": [
    {
      "id": "qwen3-32b",
      "object": "model",
      "created": 1700000000,
      "owned_by": "vllm",
      "backends": ["vllm-large", "vllm-small"],
      "metadata": {
        "limits": {
          "context_window": 32768,
          "max_output": 32768
        }
      },
      "max_model_len": 32768,
      "root": "Qwen/Qwen3-32B"
    }
  ]
}

Fields:

Upstream fields: Every other top-level key is copied from one backend's own /v1/models entry for the model (with several backends, which one is not specified). These keys are a passthrough, not a contract: they appear only when a backend sent them and keep that backend's shape. Keys the router serializes itself (id, object, created, owned_by, backends, metadata, tier, domains) are never taken from upstream.

Which value is authoritative: metadata is the router's answer and the value it acts on. Where an upstream field restates something metadata also states, read metadata:

• The context window is the one exception the router reconciles. max_model_len (vLLM-family engines) and context_length (aggregators such as OpenRouter), when present, are rewritten to metadata.limits.context_window, so the object never states two windows. That window is the operator's configured limits when metadata supplies them, otherwise the minimum that the serving backends report, since a request may reach any of them. Neither key is added when the backend did not send it, and neither is rewritten when the published context_window is 0 (not applicable).
• Every other upstream key stays verbatim. In particular an aggregator's pricing (USD per token, as strings) and top_provider.max_completion_tokens are left as the upstream sent them, while metadata.pricing (USD per 1M tokens) and metadata.limits.max_output carry the router's values folded across backends. See Upstream vendor and metadata.

Status Codes:

• 200: Models retrieved successfully
• 503: All backends are unhealthy

Query Models¶

Filter the aggregated catalog server side by capability and limit conditions. The endpoint returns the same model objects as GET /v1/models/extended, narrowed to the models the catalog proves satisfy every stated condition. A query no model satisfies is a successful response with an empty data array, not an error.

POST /v1/models/query

Request Body (all fields optional; an absent or empty body selects every visible model, so the endpoint then behaves like GET /v1/models/extended):

{
  "capabilities": ["chat", "vision"],
  "min_context_length": 64000,
  "max_output": 4096,
  "q": "gpt",
  "limit": 20
}

Fields:

The filters apply to the exact listing GET /v1/models/extended returns for the same caller (alias and experiment names, the caller's backend and model allow-lists, internal backends, and the routability filter), so a query can only narrow that listing.

Validation:

• capability is an accepted spelling of capabilities and also takes an array. A body with both spellings returns 400 (invalid_query).
• Unknown fields are rejected with 400 (invalid_query), so a misspelled filter cannot silently return every model.
• capabilities accepts at most 32 entries of 1 to 64 bytes each. Matching is exact and case-sensitive.
• q must be 1 to 256 bytes.
• limit must be 1 to 1000.
• Body size is capped at 16 KiB; a larger body returns 413.
• Scope: the route requires the read API-key scope, like the other model listings, because it changes nothing and dispatches no inference.

Example:

curl -s -X POST http://localhost:8080/v1/models/query \
  -H 'Content-Type: application/json' \
  -d '{"capabilities":["vision"],"min_context_length":64000}'

Status Codes:

• 200: Filtered model list returned (possibly empty)
• 400: The request body is present but not a valid query (OpenAI-style error object, code invalid_query)
• 413: The request body exceeds 16 KiB
• 503: All backends are unhealthy

Proxy a Backend Model List¶

Return the raw /v1/models response from one selected eligible backend instead of aggregating all backends. This compatibility endpoint uses normal backend selection, retry, health, and caller backend-visibility rules.

GET /v1/models/proxy

Use GET /v1/models for the router's deduplicated aggregate catalog. Use this endpoint only when a client needs one backend's provider-native model-list payload.

Status Codes:

• 200: Selected backend response returned
• 502: Backend connection or gateway failure
• 503: No eligible healthy backend

Force-Refresh Models¶

Synchronously re-aggregate from all configured backends and replace the model-aggregation cache. If a backend cannot be discovered, its last-known models are retained while fresh results from successful backends remain authoritative. The returned list follows the same routable-models rule as GET /v1/models. The endpoint returns the same OpenAI-compatible model list shape as GET /v1/models so the caller can use the response immediately.

This endpoint is designed for interactive "Refresh" actions in desktop clients (e.g. the "Refresh models" button in backend.ai-go). It bypasses the stale-while-revalidate and soft-TTL windows, triggering an upstream fetch from every backend before responding.

POST /v1/models/refresh

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai-compatible"
    }
  ]
}

Status Codes:

• 200: Refresh completed and the updated model list returned
• 429 Too Many Requests: Force-refresh rate limit exceeded (3 requests per 5-second burst window, 12 per minute)

Rate Limiting:

The endpoint applies a tighter budget than the regular GET /v1/models because each call triggers an upstream fetch from every configured backend. The default limits are 3 requests per 5-second window and 12 per minute. Valid API keys receive separate buckets keyed by API key ID. Anonymous callers and requests with invalid bearer tokens share one global anonymous bucket, so spoofed Authorization, X-Forwarded-For, or X-Real-IP headers cannot bypass the force-refresh budget. Clients that exceed the limit receive 429 and should wait before retrying.

Cache policy:

The model-list cache currently uses internal fixed defaults: a 60-second hard TTL, an 80% soft TTL, stale-while-revalidate, request coalescing, and bounded empty-result backoff. These values and force-refresh availability are not fields in the public configuration schema.

Get Single Model¶

Retrieve information about a specific model, including its availability status and optional rich metadata.

GET /v1/models/{model}

Path Parameters:

Response (Basic):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1677610602,
  "owned_by": "openai",
  "available": true
}

Response (With Extended Metadata):

When model metadata is available in model-metadata.yaml, the response includes additional fields. For a model served by an OpenAI-compatible aggregator such as OpenRouter, limits (and therefore max_tokens) may be reported by the upstream catalog when configured metadata has none, and an upstream price replaces pricing from the shared model-metadata.yaml or built-in catalog unless the backend's own model_configs sets one; GET /v1/models/extended carries the same metadata plus the upstream's raw fields. See Upstream vendor and metadata:

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": true,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI",
    "summary": "Frontier GPT-5.6 model for complex professional work.",
    "knowledge_cutoff": "2026-02",
    "relative_speed": 3,
    "pricing": {
      "input_tokens": 5.0,
      "output_tokens": 30.0
    },
    "limits": {
      "context_window": 1050000,
      "max_output": 128000
    }
  }
}

Response Fields:

Metadata Object Fields:

An image model's limits object carries the optional image keys alongside the token bounds. All of them are informational for API consumers: the router enforces image request limits per model family in code and does not read these values. dall-e-3 serves:

"limits": {
  "context_window": 0,
  "max_output": 0,
  "max_prompt_length": 4000,
  "supported_sizes": ["1024x1024", "1792x1024", "1024x1792"],
  "max_n": 1,
  "supported_qualities": ["standard", "hd"],
  "supported_styles": ["vivid", "natural"]
}

Every optional limits key is omitted from the response when unset, so a token model's limits object serializes exactly as it did before these fields existed.

Artifact identity¶

artifact and draft_model appear only for a self-hosted model whose operator declared them in model_configs or the metadata layer, never for a model the built-in OpenAI catalog describes. Like every other key in metadata, they come from the first serving backend's entry, in configured backends order: a later backend's model_configs override is not visible here. GET /admin/models lists every serving backend's identity under artifacts, and each usage record carries the identity of the backend that served it. artifact.source is returned verbatim to every caller, so operators must declare a stable public locator there, never a presigned or token-bearing URL.

"metadata": {
  "display_name": "Qwen 3.8 27B",
  "artifact": {
    "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "registry_version": "v2.1-fp8",
    "revision": "4c2e9a1",
    "source": "hf://Qwen/Qwen3.8-27B-FP8"
  },
  "draft_model": {
    "name": "qwen3.8-0.6b"
  }
}

Pricing Object Fields¶

input_tokens and output_tokens are per 1,000,000 tokens, the unit vendors publish list prices in. This is not the smart_routing cost_per_1k_input_tokens unit, which is per 1000 tokens; divide by 1000 to convert.

long_context contains threshold_tokens, input_tokens, and output_tokens. A prompt equal to the threshold uses the base rates. A prompt above it uses both tier rates for the whole request. The field is metadata for API consumers; router-side smart-routing tier inference continues to use the base input rate.

"pricing": {
  "input_tokens": 0.1,
  "output_tokens": 0.5,
  "long_context": {
    "threshold_tokens": 100000,
    "input_tokens": 0.5,
    "output_tokens": 2.5
  }
}

image_input_tokens and cached_image_input_tokens coexist with the text rates rather than replacing them. gpt-image-2 bills text input at input_tokens and image input at image_input_tokens:

"pricing": {
  "input_tokens": 5.0,
  "output_tokens": 30.0,
  "cached_input_discount": 0.75,
  "image_input_tokens": 8.0,
  "cached_image_input_tokens": 2.0
}

per_image values are USD per generated image, a different unit from everything above. Each key is a size (1024x1024) or a named tier (ultra), and a key holds either a single price or a nested per-quality map. All three shapes are served:

"per_image": {"1024x1024": 0.02, "512x512": 0.018, "256x256": 0.016}

"per_image": {"fast": 0.02, "standard": 0.04, "ultra": 0.06}

"per_image": {
  "1024x1024": {"standard": 0.04, "hd": 0.08},
  "1792x1024": {"standard": 0.08, "hd": 0.12}
}

A model priced per image reports input_tokens: 0 and output_tokens: 0. Those zeros are literal catalog values, not missing data; the presence of per_image is the machine-readable signal that token pricing is not that model's axis. Clients should check for per_image before rendering a 0 token rate as a price.

Every optional field above is omitted from the response when unset, so a model that carries only token pricing serializes exactly as it did before these fields existed.

Supported Methods Mapping:

The supported_methods field is derived from model capabilities:

Status Codes:

• 200: Model found and information returned
• 404: Model does not exist in any configured backend

Features:

• OpenAI-Compatible: Response format matches OpenAI API with additional extension fields
• Health-Aware: The available field reflects real-time backend health status
• Privacy: Does not expose internal backend information
• Optional Metadata: Extended fields are present only when metadata is available
• Rich Metadata: Includes display name, developer, capabilities, and context-window limits to inform client-side model selection

Model Availability Algorithm:

The available field is determined by the following algorithm:

The algorithm uses short-circuit evaluation: it returns true as soon as the first healthy backend is found, avoiding unnecessary health checks for remaining backends. This optimizes performance when backends are generally healthy.

Performance Optimization:

• Fast Path: If the model cache is valid, lookup is O(n) where n = number of models
• Slow Path: If cache is empty/expired, triggers one-time aggregation with singleflight protection to prevent cache stampede
• Stale-While-Revalidate: Cache serves stale data while refreshing in background

Example Request:

curl http://localhost:8080/v1/models/gpt-5.6-sol

Example Response (Model Available with Full Metadata):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": true,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI",
    "summary": "Frontier GPT-5.6 model for complex professional work, with text and image input.",
    "knowledge_cutoff": "2026-02",
    "relative_speed": 3,
    "pricing": {
      "input_tokens": 5.0,
      "output_tokens": 30.0
    },
    "limits": {
      "context_window": 1050000,
      "max_output": 128000
    }
  }
}

Example Response (Model Without Extended Metadata):

For models without metadata in model-metadata.yaml, only the basic fields are returned:

{
  "id": "custom-model",
  "object": "model",
  "created": 1677610602,
  "owned_by": "local",
  "available": true
}

Example Response (Model Exists but Unavailable):

{
  "id": "gpt-5.6-sol",
  "object": "model",
  "created": 1704067200,
  "owned_by": "openai",
  "available": false,
  "supported_methods": ["chat.completions"],
  "features": ["chat", "vision", "code", "reasoning", "tool"],
  "max_tokens": 128000,
  "metadata": {
    "display_name": "GPT-5.6 Sol",
    "developer": "OpenAI"
  }
}

Chat Completions¶

Generate chat completions using the OpenAI Chat API format.

POST /v1/chat/completions

Request Body:

{
  "model": "gpt-5.6-luna",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user", 
      "content": "Explain quantum computing in simple terms."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "stream": false,
  "stop": null,
  "logit_bias": {},
  "user": "user123"
}

Parameters:

Client Provider Preferences¶

With proxy.client_provider_preferences: true, a client may send OpenRouter's provider object in the request body to narrow and order the backends this request may use. The object is opt-in: with the switch off (the default) it is forwarded unchanged, exactly as before, so an aggregator backend behind a generic backend still receives it.

Supported fields:

Security and precedence:

• The candidate set is built in this order: backend visibility (internal, enabled), the key's allowed_models and allowed_backends, Hub and policy narrowing, and finally the client's provider filters. A preference can only narrow or reorder that set; it can never widen an allow-list or make an invisible or disabled backend reachable.
• only, ignore, and order naming a backend outside the candidate set has no widening effect. A filter that empties a non-empty candidate set, such as an only whose intersection is empty, answers 400 invalid_request_error naming the field (provider.only, provider.ignore, or provider.max_price) and dispatches nothing. A set that was already empty before the filters keeps the ordinary 503.
• x-backend remains a first-attempt pin and wins over provider. Retries after that first attempt apply the provider object again.
• A request that carries a provider object never joins another request's in-flight dispatch. Deduplication keys on the dispatched body, and the router removes provider from it, so two requests differing only in their preferences would otherwise share one dispatch and one could be answered from a backend it excluded. The preference therefore costs one dispatch of its own when it is present.
• With the switch on, the router consumes and removes the object, so no backend receives it. An operator can still send a provider object to a backend that speaks it through backends[].request_extensions.body.overrides.provider, which is applied at dispatch after the client key is removed. request_extensions.body.defaults.provider cannot restore the removed client object, because defaults only fill unset keys. Static operator configuration therefore wins over the client object, and the client object never reaches an upstream verbatim.
• With the switch off, nothing changes: the object passes through as it does today.

Refused fields: An unknown field is a 400 naming provider.<field>, including OpenRouter fields this router does not implement (allow_fallbacks, quantizations, and similar). A silently ignored routing preference is worse than a rejected one. Two known OpenRouter fields are refused by name for the same reason: the router cannot prove that every request parameter survives every candidate's conversion, so it does not accept require_parameters: true, and it has no per-backend data-collection metadata, so it does not accept data_collection: "deny".

Validation limits: The serialized object is limited to 16 KiB. Each name list is limited to 16 entries, and each name is 1 to 128 bytes with no leading or trailing whitespace and no control characters. Duplicates are collapsed preserving first occurrence. provider must be a JSON object. Every refusal to parse the object answers 400 invalid_request_error with param: "provider". A filter the candidate set cannot satisfy answers the same status and type, with the field named in the message.

Ranking fallback: sort and order rank only on stated data. A candidate with no fresh engine snapshot or no recorded latency joins one trailing rank group, and a fleet with no telemetry at all produces a single group. In that case selection is exactly the configured selection_strategy: a preference never reorders on absent data. max_price is stricter: an unpriced candidate is excluded, because its price cannot be verified.

Candidates equal on every stated key form one rank group: equal on their order position (or absence from the list) and, when stated, on the sort metric. The configured selection_strategy chooses within that group, so equal prices or equal order ranks still rotate instead of pinning the first candidate.

The Anthropic Messages ingress refuses a top-level provider key with 400 while the switch is on, rather than silently dropping it, because that ingress does not apply client routing preferences.

Input context limit¶

The router rejects a chat input estimated to fill or exceed the routed model's context_window before backend dispatch, for buffered and streaming requests. The response is 400 invalid_request_error with code context_length_exceeded and a message containing the window and estimated input tokens. This also applies when no output-token budget is supplied.

By default the rejection does not trigger a larger-model fallback. With fallback.fallback_policy.trigger_conditions.context_window_exceeded: true, the router instead hops before dispatch to the first configured chain target whose own window fits the input, and answers the original rejection only when no target fits. See Context-window fallback.

The estimate includes messages and tool schemas, uses the same typical estimate as fallback admission, and runs after model routing and optional context compression. It is an approximation, not a model-specific tokenizer count. Missing or zero context limits allow the request through.

For each authorized serving backend, configured limits override cached engine reports. The smallest known positive window is enforced across these backends, as in fallback admission, even if another backend has a larger or unknown window. This is more conservative than output-budget validation. If metadata understates a backend's real window, correct the model metadata to restore requests that previously succeeded.

Valid reasoning_effort values by backend:

For detailed conversion tables and backend-specific behavior, see Reasoning Effort Architecture.

For OpenAI models, the router applies the same exact model-specific validation to streaming and non-streaming requests. Unsupported values return 400 invalid_request_error; the router never rewrites auto, xhigh, or max to a different effort. Other providers retain their provider-specific conversion behavior shown above.

Response (Non-streaming):

{
  "id": "chatcmpl-123456789",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses quantum mechanical phenomena like superposition and entanglement to process information..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

Response (Streaming): When stream: true, the response uses Server-Sent Events (SSE):

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"content":"Quantum"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{"content":" computing"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.6-luna","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Status Codes:

• 200: Completion generated successfully
• 400: Invalid request format or parameters
• 404: Model not found on any healthy backend
• 502: Backend connection error
• 504: Request timeout
• 503: All backends unhealthy

Features:

• Model-Based Routing: Automatically routes to backends serving the requested model
• Load Balancing: Distributes load across healthy backends
• Streaming Support: Real-time response streaming via SSE
• Error Recovery: Automatic retry on transient failures
• Request Deduplication: Prevents duplicate processing of identical requests
• Reasoning Parameter Normalization: Automatically normalizes nested reasoning format to flat reasoning_effort format; removes reasoning parameters for models that don't support them
• Transparent Responses-API routing: Models marked responses_only: true (such as gpt-5-pro, gpt-5.2-pro, gpt-5.4-pro, and gpt-5.5-pro) are transparently dispatched to the upstream /v1/responses endpoint and translated back into a strict-mode chat.completion (or chat.completion.chunk for streaming) envelope:
  • Preserves reasoning_content, refusal (finish_reason: "content_filter"), incomplete_details truncation (finish_reason: "length" or "content_filter"), and upstream failed or cancelled error envelopes.
  • Supported on OpenAI and Azure OpenAI backends only; pairing a responses_only model with another backend type returns 400 invalid_request_error before dispatch. See Responses-API-only Models.
• Gemini Native API Routing: When dispatching to a Gemini backend, requests using native-exclusive features (tools: [{"google_search": {}}], tools: [{"code_execution": {}}], modalities: ["text", "image"], cachedContent, multi-turn assistant image history, or gemini_context_cache.prefer_native_api: true) automatically route to Gemini's native generateContent / streamGenerateContent endpoint, transforming responses into OpenAI-compatible format with reasoning_content, code_execution, annotations, grounding_metadata, and inline images.

Gemini Native Exclusive Feature Examples (/v1/chat/completions)¶

1. Google Search Grounding & Code Execution:

{
  "model": "gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": "Search Google for the latest stable Rust release and use Python to compute the days since its release."
    }
  ],
  "tools": [
    { "type": "google_search" },
    { "type": "code_execution" }
  ]
}

The normalized chat.completion response includes annotations (type: "url_citation"), grounding_metadata, and structured code_execution items alongside the formatted content:

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "```python\nprint(42)\n```\n\n```output\n42\n```\nThe latest release is...",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "url": "https://...",
              "title": "rust-lang.org",
              "start_index": 0,
              "end_index": 24
            }
          }
        ],
        "grounding_metadata": {
          "webSearchQueries": ["latest stable Rust release"],
          "groundingChunks": [],
          "groundingSupports": []
        },
        "code_execution": [
          { "type": "executable_code", "language": "PYTHON", "code": "print(42)\n" },
          { "type": "code_execution_result", "outcome": "OUTCOME_OK", "output": "42\n" }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

2. Multi-turn Conversational Image Generation & Editing:

Pass modalities: ["text", "image"] with a Gemini image model (gemini-2.5-flash-image, nano-banana, nano-banana-2, nano-banana-pro) and include the previous turn's assistant.images array to iteratively edit an image across turns:

{
  "model": "gemini-2.5-flash-image",
  "modalities": ["text", "image"],
  "messages": [
    { "role": "user", "content": "Generate a flat icon of a blue circle." },
    {
      "role": "assistant",
      "content": "",
      "images": [
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." }
        }
      ]
    },
    { "role": "user", "content": "Change the circle color from blue to red and add a yellow star." }
  ]
}

Tool conversion warnings¶

Successful responses include x-continuum-dropped-tools when the router omits tool declarations while converting the request for the serving backend. This applies to Chat Completions, Responses, and Anthropic Messages bridges, including streaming responses. Requests retain their existing permissive behavior; inspect this header if your application requires every declared tool.

The value is a sorted, comma-separated list of distinct type names. Known names are web_search, web_search_preview, file_search, code_interpreter, computer_use_preview, image_generation, mcp, local_shell, and custom; all other types are grouped as other. The header is exposed through CORS. For example:

x-continuum-dropped-tools: file_search, other

Only tools actually omitted are listed. Gemini search and code execution tools translated to native built-ins are not omissions. A failed upstream attempt contributes no warning to a successful fallback response. For streams, the header describes conversion completed during the serving handshake; subsequent OpenAI-wire relay hops preserve the tool declarations.

Router response caching is bypassed for requests containing non-function tools, including native tool declarations, because cached bodies do not preserve conversion warnings. This affects exact, prefix, and semantic response caches; requests containing only function tools remain eligible. Provider prompt/context caches are unchanged.

Responses API¶

Generate responses using OpenAI's Responses API format. This endpoint provides an alternative interface to Chat Completions, internally converting requests to the Chat Completions format for backend processing.

A streamed response that the client cancels, that times out, that a guardrail blocks, or that fails mid-stream is charged for the tokens generated up to the cut: one usage record with that exit's outcome, from the engine's usage when it arrived and the router's delta count otherwise. An Anthropic or Gemini upstream cut after reporting its input but before its output count (Anthropic's message_delta, Gemini's terminal candidatesTokenCount) is charged that input beside the router's delta count.

POST /v1/responses

Request Body:

{
  "model": "gpt-5.6-sol",
  "input": "Explain quantum computing in simple terms.",
  "instructions": "You are a helpful assistant that explains complex topics simply.",
  "max_output_tokens": 1000,
  "temperature": 0.7,
  "reasoning": {
    "effort": "high"
  }
}

Parameters:

Fields the router does not model (conversation, background, service_tier, parallel_tool_calls, and fields the API adds later) are forwarded to a pass-through backend exactly as sent. The conversion strategies build their request from the fields above and drop the rest, and a request carrying any such field is never served from the response cache. Input items of a type the router does not model (for example mcp_approval_response or computer_call_output) are likewise kept verbatim for a pass-through backend; a conversion strategy refuses them with 400 unsupported_request_parameter instead of dropping them.

Tool types beyond the built-in list keep the same rule, which is what lets Codex CLI reach a backend through this endpoint. A pass-through backend receives each tool the responses_tools policy allows, with the same JSON content the client sent; object key order is not preserved. A conversion strategy handles them as follows:

The policy runs before backend selection on both flows, so a type it refuses gets 400 unsupported_request_parameter naming tools[<type>] on every backend, and no upstream request is made. tool_search with execution: "client" is always allowed, and with any other execution it follows the "any other type" row.

Two flattened names that collide are also refused with 400 unsupported_request_parameter. A tool of a known type with a missing required field, such as a function tool without name, fails with 422.

A conversion strategy also refuses a request whose tools flatten to more than 4096 entries, counting each namespace member as one entry, with 400 unsupported_request_parameter. Flattening cost grows with that count, and a request at the 10 MiB body limit costs far more CPU than one request may spend. A pass-through backend is unaffected: it sends the tools as declared and flattens nothing.

A converted reply, streaming or not, reports a call to a flattened tool under the original name with its namespace, so a client that dispatches on that pair can route it.

Modeled shapes also keep fields the router does not model. A pass-through backend receives them unchanged, and a conversion strategy ignores them:

• Hosted tools: web_search (for example external_web_access or filters), file_search (vector_store_ids), code_interpreter (container), computer_use, and programmatic_tool_calling.
• Replayed items: message (id, status, and any other field, also on an item with role and content and no type; with a type, phase, agent, caller, or a non-standard id or status makes it a native-only item that a conversion strategy refuses), function_call (id, status, encrypted_content, encrypted_function_args) and function_call_output (id, status). These fields count toward the input size limit.

A backend may reject a replayed id it does not know, for example under store: false, exactly as it would if called directly.

tool_choice shapes:

Any other value, such as an unknown string, {"type": "function"} without name, or a named object whose namespace is not a string, fails with 422. On the Gemini conversion, tool_choice becomes tool_config only when the request declares a function tool. A request with only web_search or code_interpreter has no tool_config, so a forced choice has no effect there. A request that combines a function tool with web_search or code_interpreter needs a model with server-side tool circulation: gemini-2.5-flash rejects it with a 400 unless tool_choice is none. Tools Gemini ran itself come back as a reasoning item with an opaque encrypted_content, and a function_call can carry encrypted_content too. Later Gemini models answer a replayed call without it with a 400, so a client that manages its own history must send both fields back unchanged.

The reasoning item's encrypted_content is signed by the router instance that issued it; a value whose signature does not verify (after a restart, or on another instance) is dropped instead of replayed. Its server-side tool parts are inspected on output, and a masking verdict removes the item.

On /v1/chat/completions, a Gemini native request follows these tool rules:

• When toolConfig is sent: only when function declarations are reachable, either inline or through a cachedContent the client manages. A request with only built-in tools (web_search_options, code_execution, and similar) sends none, so a required or named choice is validated but not enforced. Each such request logs a warning and increments tool_choice_unenforced_total{reason="forced_without_functions"}.
• Functions next to a built-in: toolConfig carries include_server_side_tool_invocations: true, including when the client sends no tool_choice. A model that does not support the mix still rejects it with a 400, as gemini-2.5-flash does.
• tool_choice: "none": the router removes built-in tools from the body, including one derived from web_search_options, so the request runs with no tools. Each removal increments tool_choice_unenforced_total{reason="none_with_built_ins"}.

A Gemini 4xx on either surface keeps Google's sanitized message in the client-facing error, for example Invalid tool. A 5xx body is never forwarded, and the client sees the status-derived message.

Tool Definition Format:

The Responses API uses a flat tool format where function properties are at the same level as the type field. This differs from the Chat Completions API which uses a nested function object.

{
  "type": "function",
  "name": "get_weather",
  "description": "Get weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "City name"}
    },
    "required": ["location"]
  },
  "strict": true
}

Other supported tool types include code_interpreter, file_search, web_search, and computer_use. When targeting a Gemini backend, web_search automatically maps to native google_search grounding (surfacing url_citation annotations and grounding_metadata), and code_interpreter maps to native code_execution (surfacing formatted code blocks and execution results).

On a Gemini backend, a turn that ends on a tool-related or malformed finish reason such as MALFORMED_FUNCTION_CALL or TOO_MANY_TOOL_CALLS reports status: failed with the lowercased reason as error.code, and a reply with no candidates and no prompt block reports failed with empty_response, in streaming and non-streaming responses alike. A failed reply is HTTP 200 but served no reply: it is returned as-is, never cached, never stored for a previous_response_id continuation, and never used for the usage-quality judgment, and the request records upstream_error while still charging the tokens the provider reported.

Multi-Modal Input Types:

When input is an array of items, each item can be a message containing multi-modal content parts. The following content part types are supported:

Message Roles:

Each message item carries one of five roles. The router accepts all five for /v1/responses and translates them per backend.

The router preserves arrival order when multiple developer and system messages are present. When the target backend (Anthropic, Gemini) only accepts a single instruction slot, the router concatenates them with a blank-line separator so no instruction text is silently dropped.

Item References:

An input item of the form {"type": "item_reference", "id": "item_..."} points at an output item from a previously stored response. This is how the OpenAI and Vercel AI SDKs submit multi-step tool round-trips by default: instead of echoing the full function-call item back, step 2 references the item produced in step 1.

• On the OpenAI / Azure OpenAI passthrough path, references are forwarded unchanged and the upstream resolves them.
• On the converted paths (Anthropic, Gemini, and chat-completions-backed routes), the router resolves each reference from its session store before dispatch, rewriting it to the inline function_call, message, or function_call_output item it points to. References are de-duplicated by call_id (first wins).
• Streamed responses participate as well: the accumulated response is stored when the stream completes, so a follow-up request can reference items produced by a streaming step.
• An unresolvable reference returns HTTP 400 naming the id, and a request may carry at most 256 references.

Input File Format:

The input_file content part supports three input methods:

{
  "type": "input_file",
  "filename": "document.pdf",
  "file_data": "data:application/pdf;base64,JVBERi0xLjQ..."
}

Input Image Format:

{
  "type": "input_image",
  "image_url": "data:image/png;base64,iVBORw0KGgo...",
  "detail": "high"
}

Exactly one of image_url or file_id must be present. A part with neither is rejected with 400. When file_id is provided, the file is resolved to an inline base64 data URL before the request reaches the backend; file ownership is verified and a 10MB size limit applies, matching the input_file + file_id path.

Multi-Modal Request Example:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "What does this document say?"},
          {"type": "input_file", "filename": "report.pdf", "file_data": "data:application/pdf;base64,..."}
        ]
      }
    ]
  }'

Security Notes:

• External URLs in file_url are validated to prevent SSRF attacks
• Private IP addresses and localhost URLs are rejected
• Only HTTPS URLs are recommended for external files
• The file_id field references files uploaded via the Files API. Files are resolved and converted to base64 before sending to backends. File ownership is verified and a 10MB size limit applies for file injection

Reasoning Parameter:

The reasoning parameter controls the reasoning effort level for reasoning-capable models. It uses a nested format:

{
  "reasoning": {
    "effort": "high"
  }
}

Valid effort values:

The router automatically converts this nested format to the flat reasoning_effort format used by Chat Completions backends. Invalid effort levels are rejected with a 400 Bad Request error.

Example Request with Reasoning:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o1",
    "input": "Solve this complex mathematical problem step by step.",
    "reasoning": {
      "effort": "high"
    }
  }'

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "o1",
  "output": [
    {
      "type": "message",
      "id": "msg_001",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Let me solve this step by step..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150
  },
  "status": "completed"
}

Status Codes:

• 200: Response generated successfully
• 400: Invalid request format, parameters, or invalid reasoning effort value
• 404: Model not found on any healthy backend
• 502: Backend connection error
• 504: Request timeout
• 503: All backends unhealthy

Features:

• Smart Routing: Routes requests based on backend capabilities - native pass-through for OpenAI/Azure and for backends configured with responses_api: native, automatic conversion for others
• Native Pass-through: For OpenAI and Azure OpenAI backends, and any OpenAI-wire backend configured with responses_api: native, requests are forwarded directly to the backend's /v1/responses endpoint, preserving all native features
• Automatic Conversion: For other backends (Anthropic, Gemini, vLLM, Ollama, etc.), converts Responses API format to their native format
• Reasoning Support: Full support for reasoning parameter with type-safe validation
• Multi-Backend Support: Works with OpenAI, Anthropic, Gemini, Ollama, vLLM, and other backends
• Streaming Support: Real-time response streaming via SSE when stream: true
• Session Management: Supports multi-turn conversations via previous_response_id

Routing Strategy:

The router automatically determines the best strategy for each backend:

The table is each type's default. A self-hosted server that implements the Responses API itself, such as an agent runtime that keeps its own conversation state or SGLang's /v1/responses, can be served unchanged by setting responses_api: native on its backend (see Backends: Native Responses API). The option is accepted on every type that speaks the OpenAI wire format (openai, azure, generic, continuumrouter, vllm, sglang, tensorrt-llm, ollama, llamacpp, mlxcel, lmstudio) and refused at load on anthropic, bedrock, and gemini. It changes only how /v1/responses (and /v1/responses/compact) reach the backend: model listing, owned_by, health checks, and every other endpoint keep the type's behavior.

On the pass-through strategy the backend receives the request as the client sent it, including previous_response_id, conversation, and input items the router does not model (for example mcp_approval_response), and its output reaches the client unchanged on both the streaming and the non-streaming path, including output items the router does not model (for example mcp_approval_request). The responses_tools.deny_resource_fields list can refuse the previous_response_id, conversation, and prompt fields, item_reference input items, and, through input_item_resource_ids, any input item that carries a resource ID such as a file_id or a container_id; these entries are off by default.

Three exceptions keep governance in force. background: true is forwarded only on the pass-through strategy (see Background responses); a conversion strategy drops it and answers synchronously. While the guardrail policy applies to the request's model and key, a reusable prompt is treated as uninspectable input (enforce mode refuses it, monitor mode records it), since its variables are not read by the input stage. While request_params or a hub tier limit governs top_k, min_p, or max_tokens, the unmodeled fields top_k, min_p, max_tokens, and max_completion_tokens are refused with 400 rather than forwarded past the bound.

Pass-through Benefits:

When using OpenAI or Azure OpenAI backends with pass-through mode:

• Native PDF file support (Chat Completions only supports images)
• Preserved reasoning state between turns for better performance
• Access to built-in tools (web_search, file_search, etc.)
• Better cache utilization (40-80% improvement per OpenAI documentation)
• Full compatibility with the latest OpenAI Responses API features

Anthropic Native Conversion Benefits:

When using Anthropic (Claude) backends with native conversion:

• Native PDF file support via Anthropic's document understanding
• Image file support with automatic format detection
• Extended thinking support for Claude 3+ models
• SSRF protection for external file URLs
• Media type whitelisting for security

Guardrails: When guardrails are configured, this endpoint runs the input stage on every request, streaming or not, before the response cache, backend selection, and any fallback attempt, and the output stage on every non-streaming reply before a store: true session is written. A blocked request is answered with a response object whose status is incomplete and whose incomplete_details.reason is content_filter (HTTP 200), or with the OpenAI content_filter error envelope (HTTP 400) under block_behavior: error, before any SSE event is sent. On the conversion strategies a previous_response_id or item_reference continuation is checked again over the rebuilt history, under the dispatched model's policy. A block is never cached and never triggers a fallback hop. See Guardrails: Coverage by route.

Retrieve, Delete, or Cancel a Stored Response¶

Responses created with store: true can be retrieved, deleted, or cancelled by ID:

• Storage and routing:
  • Conversion strategies: Served from the router's in-memory session store (up to 10,000 sessions per router instance, 1-hour TTL). Multiple router instances embedded in the same process (such as via serve_embedded) maintain separate stores.
  • Pass-through backends: Stored by the upstream backend itself; the router forwards the request to the backend that created the response (see Pass-through Responses).
• Ownership and scoping: Sessions are scoped to the authenticated API-key principal (api_keys[].user_id) that created the response. Authorization: Bearer <key> and X-API-Key: <key> share the same identity namespace. Missing, expired, unauthenticated, or cross-principal requests return 404.

Migration from X-User-ID Scoping¶

X-User-ID is not an authorization boundary for the Responses API. The router ignores it for stored response access, previous_response_id context reconstruction, item-reference resolution, and local Files API ownership checks, and it is not forwarded to backends. Deployments that previously multiplexed multiple end users behind one shared router API key by setting X-User-ID must migrate to one router API key per isolated user or tenant, or place their own trusted service in front of the router and keep per-user state outside the router's stored Responses session and Files API ownership controls.

GET /v1/responses/{response_id}
DELETE /v1/responses/{response_id}
POST /v1/responses/{response_id}/cancel

A successful GET returns the stored response object. A successful DELETE returns:

{
  "id": "resp_abc123",
  "object": "response.deleted",
  "deleted": true
}

Pass-through Responses¶

When a pass-through backend serves a store: true response, the router remembers which backend served its id, under the authenticated principal that created it. GET, DELETE, and POST .../cancel on that id are then forwarded to the same backend with its configured credential, and the backend's status, Content-Type, and body are returned (a GET query string such as ?stream=true is forwarded too). A successful DELETE also forgets the binding. A response the guardrail output stage blocked, masked, or cut is not bound, because the backend's stored copy is the unfiltered text; GET on it answers 404.

The router never sends an id it did not record to any backend, and re-checks the binding on every call against the live configuration: the backend must still be configured, enabled, not internal, and served through pass-through, and the caller's key must still be allowed to reach it (allowed_backends). A call that fails any check answers the same 404 as an unknown id, without contacting a backend. The bindings are held in memory per router instance, at most 10,000 (the oldest is forgotten first), and are lost on restart; a forgotten id also answers 404. cancel on a response the router produced itself answers 400, because such a response is already complete.

Background responses¶

A background: true request on a pass-through backend is forwarded as sent, and the backend answers queued (or in_progress) at once and finishes the response later. Admission (rate limits, local and hub budgets) runs at that POST as for any request.

• Metering. The queued answer records nothing. The first time the router relays the terminal result (completed, incomplete, failed, or cancelled) carrying usage, through GET /v1/responses/{id} or POST .../cancel, it records the request and its usage once, through the same path a synchronous reply uses, attributed to the key that created the response, even when another key of the same principal fetches it. A repeat fetch records nothing.
• Guardrails. While the guardrail policy applies to the request's model and the fetching key, every fetch of the result passes the output stage before it is relayed, and a block or mask applies as on a synchronous reply. stream: true together with background: true is refused with 400 unsupported_request_parameter while a guardrail applies, since a client could resume that stream later through GET ?stream=true, which the router cannot gate.
• Streamed background without guardrails is forwarded and metered once: by the stream at its terminal event when the client stays connected, otherwise by the first non-streamed GET or cancel of the terminal result, since the router stops reading the stream when the client disconnects while the backend keeps generating.
• Replays. GET ?stream=true on a background result that is still unmetered (including a streamed one whose client disconnected before the terminal event), or while a guardrail applies, is refused with 400 unsupported_request_parameter; fetch it without stream.
• Limitation. A background result that is never fetched through the router (fetched from the backend directly, or not at all) is not metered: the router learns the usage only when it relays the result, and it does not poll backends on its own. The binding that holds the pending record is in memory per router instance and is lost on restart or eviction.

Responses Compact¶

Compact a conversation context by summarizing or compressing a sequence of input items. For OpenAI and Azure OpenAI backends, and backends configured with responses_api: native, the request is forwarded directly to the backend's native /v1/responses/compact endpoint. Other backends return HTTP 501 (Not Implemented), as context compaction is not natively supported.

When guardrails are configured, the input items and instructions go through the input stage before a backend is selected, and a block is always answered with the OpenAI content_filter error envelope (HTTP 400). The compaction output is opaque and is not gated. See Guardrails: Coverage by route.

POST /v1/responses/compact

Request Body:

{
  "model": "gpt-5.6-sol",
  "instructions": "Summarize the key points from this conversation.",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "What is the capital of France?"}]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "The capital of France is Paris."}]
    }
  ]
}

Parameters:

Response:

{
  "id": "cmpt_abc123",
  "object": "response.compaction",
  "created_at": 1699000000,
  "output": [
    {
      "type": "text",
      "text": "Compacted conversation summary..."
    }
  ],
  "usage": {
    "input_tokens": 120,
    "output_tokens": 45
  }
}

Status Codes:

• 200: Compaction successful
• 400: Invalid request (empty model, empty input, instructions too long)
• 501: Backend does not support native context compaction
• 502: Backend connection error
• 504: Request timeout

Batch API (control-plane builds)¶

The OpenAI-style Batch API is compiled only with the control-plane Cargo feature. It is absent from default source builds. Official release binaries compile the feature, but the routes remain inert unless control_plane.enabled, policy enforcement, and control_plane.batch.enabled are active and the Hub marks the presented key/tier as batch-eligible.

A hub-synced API key is required. Ownership checks deliberately return the same 404 for unknown and other-key IDs. Results return 409 until available. The selected batch backend may be OpenAI-compatible or native Anthropic; the router presents one common surface. x-continuum-batch: off always opts a request out and cannot be overridden by policy.

For OpenAI-style batch creation, input_file_id may identify either a provider-owned file or a file in Continuum Router's local /v1/files storage. Provider-owned IDs are forwarded unchanged. For a router-local file, the router enforces the Files API ownership policy, requires purpose=batch, and refuses metadata larger than 200 MiB before reading content. After deferral and batch-pool admission, it streams the file once to the selected OpenAI-compatible backend with that backend's URL, credentials, and request extensions, then substitutes the returned provider file ID in the batch request. Native Anthropic batches use inline requests and do not accept a router-local input_file_id.

Before forwarding POST /v1/batches, the router checks the selected backend against the API key's allowed_backends. It also intersects the Hub tier's model_allowlist with the key's local allowed_models; an explicit empty Hub allow-list denies every model. Native Anthropic batches are checked from every requests[].params.model. For an OpenAI-style batch with a model restriction, the router scans a router-local file before upload, or fetches a provider-owned file with that backend's credentials, to check every JSONL body.model. An unrestricted OpenAI-style batch skips the model scan and may use the request's model hint only for usage attribution.

The input scan accepts at most 200 MiB in total and 16 MiB per JSONL record, and has a 60-second deadline. Invalid file IDs, malformed JSONL, missing models, fetch failures, and oversized inputs fail closed. These checks finish before deferral or batch-pool admission. A router-local scan reads storage as a stream and retains only the current bounded JSONL record. An unrestricted deferred request retains file metadata, not file content.

After admission, the router resolves the backend again. If its name, URL, credentials, provider type, or request extensions changed during a configuration reload, it releases the slot and returns batch_backend_changed without creating the provider batch.

The provider upload is a single attempt. A failed upload returns the provider error, or batch_input_upload_failed for a transport failure, without creating the batch. Retrying the client request can create another provider file if the first upload reached the provider but its response was lost. After a successful submission, the provider copy follows the provider's retention policy; deleting the router-local file does not cancel the batch or delete the provider copy.

Fine-Tuning API¶

The OpenAI Fine Tuning job routes are forwarded to a selected OpenAI-wire backend. Create, retrieve, and cancel return the backend's answer unchanged; the list body keeps only the caller's own jobs. They are mounted on every build, unlike the feature-gated Batch API.

Only the openai and generic backend types on http or https are candidates. Azure OpenAI is excluded because its fine-tuning endpoint is a different path with a required api-version. A request that no candidate can serve returns 400 fine_tuning_not_supported, not a router-level 404.

The router records (principal, job id) to the backend that created the job. Retrieve and cancel re-check that binding against the live configuration and the caller's allowed_backends; an unknown or foreign id returns 404 fine_tuning_job_not_found without contacting the backend. The list keeps only the entries the router bound to the caller, so it never discloses another principal's job ids or training-file ids. The binding is held in process memory, so a job created before a router restart is not listed and answers not-found.

Job CRUD applies auth, rate limiting, and usage attribution but not request-parameter policy, guardrails, response caching, or the per-model generation budget. Each call is recorded as a non-completion request with zero tokens. A training_file or validation_file must already exist on the selected backend: a router-local /v1/files id is not uploaded to the provider.

Vector Stores API¶

The OpenAI Vector Stores routes are forwarded to a selected OpenAI-wire backend. Store and file operations return the backend's answer unchanged; a list body keeps only the caller's own stores. They are mounted on every build.

Only the openai and generic backend types on http or https are candidates. Azure OpenAI is excluded because its Vector Stores endpoint is a different path with a required api-version. A request that no candidate can serve returns 400 vector_stores_not_supported, not a router-level 404.

A store call names no model, so the x-backend header is not consulted. Create and list select one capable backend with the configured selection strategy. The router then records (principal, store id) to the backend that created the store, and every store-scoped call re-checks that binding against the live configuration and the caller's allowed_backends. An unknown or foreign id returns 404 vector_store_not_found without contacting the backend. The list keeps only the entries the router bound to the caller, so it never discloses another principal's store ids. Its has_more, first_id, and last_id fields still describe the backend page, so a caller pages until has_more is false. The binding is held in process memory, so a store created before a router restart is not listed and answers not-found.

An attachment names a provider file id on the shared backend credential. The router does not record which principal uploaded a provider file, so a provider file id that leaks can be attached to another principal's store and read through search. Do not share one provider credential across tenants that must not see each other's files.

These routes apply auth, API-key scope, rate limiting, and usage attribution but not request-parameter policy, guardrails, response caching, or the per-model generation budget. Each call is recorded as a non-completion request with zero tokens. JSON request bodies are bounded at 1 MiB. An attachment names a provider file id: a router-local /v1/files id is not uploaded to the provider.

Image Generation¶

Known model capabilities are checked before image generation, editing, or variations reach a backend. If the requested operation is absent from a non-empty capability list, the router returns HTTP 400 with unsupported_model_capability and param: "model". Models with absent or empty capability lists remain eligible, including custom image editing models. Backend-specific capability overrides restrict selection to compatible backends.

Generate images using OpenAI's DALL-E, GPT Image models, or Google's Nano Banana (Gemini) models.

POST /v1/images/generations

Request Body:

{
  "model": "dall-e-3",
  "prompt": "A serene Japanese garden with cherry blossoms",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard",
  "response_format": "url"
}

Parameters:

Model-specific constraints:

Quality Parameter (GPT Image Models):

For GPT Image models, standard maps to medium and hd maps to high.

Output Format Options (GPT Image Models):

Note: Transparent background (background: "transparent") requires png or webp format.

Nano Banana (Gemini) Models:

Nano Banana provides access to Google's Gemini image generation capabilities through an OpenAI-compatible interface:

• nano-banana / nano-banana-2: Maps to Gemini 3.1 Flash Image (gemini-3.1-flash-image) - fast, general-purpose image generation with up to 4K resolution and optional Google Search grounding (google_search: true). nano-banana mapped to gemini-2.5-flash-image until Google limited that model to projects that already used it on 2026-09-18; that id still passes through when named directly.
• nano-banana-2-lite: Maps to Gemini 3.1 Flash Lite Image (gemini-3.1-flash-lite-image) - lightweight 1K image generation.
• nano-banana-pro: Maps to Gemini 3 Pro Image (gemini-3-pro-image) - advanced model with high-resolution support (up to 4K) and optional Google Search grounding (google_search: true).

Nano Banana requests go to Google's Gemini API with the selected backend's key, so only a backend configured with type: gemini serves them. A backend of any other type is never selected, whatever its name or URL: a type: openai or generic backend pointed at Google's OpenAI-compatible endpoint (https://generativelanguage.googleapis.com/v1beta/openai) must be changed to type: gemini to serve Nano Banana.

Nano Banana Size Mapping:

The router automatically converts OpenAI-style size parameters to Gemini's aspectRatio and imageSize format:

The conversion sends the following Gemini API structure:

{
  "contents": [{"parts": [{"text": "Your prompt"}]}],
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "3:2",
      "imageSize": "1K"
    }
  }
}

Example Nano Banana Request:

{
  "model": "nano-banana",
  "prompt": "A white siamese cat with blue eyes, photorealistic",
  "n": 1,
  "size": "1024x1024",
  "response_format": "b64_json"
}

Response:

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/...",
      "revised_prompt": "A tranquil Japanese garden featuring..."
    }
  ]
}

Response (with b64_json):

{
  "created": 1677652288,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAA...",
      "revised_prompt": "A tranquil Japanese garden featuring..."
    }
  ]
}

Nano Banana Response Notes:

• When using response_format: "url" with Nano Banana, the image is returned as a data URL (data:image/png;base64,...) since Gemini's native API returns inline base64 data
• The revised_prompt field contains any text response from Gemini describing the generated image
• When google_search: true is used (or tools: [{"google_search": {}}]), any groundingMetadata returned by Gemini is preserved as grounding_metadata at the top level of the image response
• When using /v1/chat/completions or /v1/responses with a Gemini backend, requests that include tools: [{"google_search": {}}], tools: [{"code_execution": {}}], modalities: ["text", "image"], cachedContent, or gemini_context_cache.prefer_native_api: true automatically dispatch to Gemini's native generateContent / streamGenerateContent endpoint and surface annotations, grounding_metadata, code_execution, and inline images in the OpenAI response format

Streaming Image Generation (GPT Image Models):

When stream: true is specified for GPT Image models, the response will be streamed as Server-Sent Events (SSE):

Example Streaming Request:

{
  "model": "gpt-image-1",
  "prompt": "A beautiful sunset over mountains",
  "stream": true,
  "partial_images": 2,
  "response_format": "b64_json"
}

Streaming Response Format:

data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"...","created":1702345678}

data: {"type":"image_generation.partial_image","partial_image_index":1,"b64_json":"...","created":1702345679}

data: {"type":"image_generation.complete","b64_json":"...","created":1702345680}

data: {"type":"image_generation.usage","usage":{"input_tokens":25,"output_tokens":1024}}

data: {"type":"done"}

SSE Event Types:

Example GPT Image Request with New Options:

{
  "model": "gpt-image-1.5",
  "prompt": "A white cat with blue eyes, photorealistic",
  "size": "auto",
  "quality": "high",
  "output_format": "webp",
  "output_compression": 85,
  "background": "transparent",
  "response_format": "b64_json"
}

Status Codes:

• 200: Image(s) generated successfully
• 400: Invalid request (e.g., invalid size for model, n > 1 for DALL-E 3)
• 401: Invalid API key
• 429: Rate limit exceeded
• 500: Backend error
• 503: Gemini backend unavailable (for Nano Banana models)

Timeout Configuration: Image generation requests use a configurable timeout (default: 3 minutes). See timeouts.request.image_generation in configuration.

Image Edit (Inpainting)¶

Edit existing images using OpenAI's inpainting capabilities or Gemini's natural-language editing. This endpoint allows you to modify or combine one or more input images based on a text prompt and optional mask. Supports GPT Image models, Nano Banana (Gemini) models, and DALL-E 2.

POST /v1/images/edits
Content-Type: multipart/form-data

Request Parameters (multipart/form-data):

Supported Models, Sizes, and Input Image Limits:

Note: DALL-E 3 does NOT support image editing via this endpoint. Nano Banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro) and Gemini image models support natural-language editing and multi-image composition (up to 14 input images); when a mask field is supplied for Nano Banana, it is ignored with a warning because Gemini determines edit regions from the prompt text.

Image Requirements:

• Field name: image or image[] (repeat the field to send multiple input images)
• Size: Less than 4MB per image
• Count limit: Up to 16 images for gpt-image-*, up to 14 images for nano-banana / nano-banana-2 / nano-banana-2-lite / nano-banana-pro / Gemini image models, and 1 image for dall-e-2
• Format and dimensions:
  • gpt-image-*: PNG, JPEG, or WebP (non-square dimensions allowed)
  • nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro: PNG, JPEG, WebP, HEIC, or HEIF (non-square dimensions allowed)
  • dall-e-2: PNG only, must be square (width equals height)

Mask Requirements:

• Format: PNG with alpha channel (RGBA)
• Dimensions: Must match the first source image (images[0]) exactly
• Transparent areas: Indicate regions to edit/generate
• Opaque areas: Indicate regions to preserve

Example Request:

curl -X POST http://localhost:8080/v1/images/edits \
  -F "image=@source_image.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool containing a flamingo" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "response_format=url"

Example Request (multiple input images):

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=gpt-image-2" \
  -F "image[]=@subject.png" \
  -F "image[]=@background.png" \
  -F "prompt=Place the subject from the first image into the background of the second image" \
  -F "n=1" \
  -F "size=1024x1024"

Response:

{
  "created": 1677652288,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
    }
  ]
}

Response (with b64_json):

{
  "created": 1677652288,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAA..."
    }
  ]
}

Status Codes:

• 200: Image(s) edited successfully
• 400: Invalid request (e.g., non-square image, invalid size, missing required field)
• 401: Invalid API key
• 503: OpenAI backend unavailable

Error Examples:

Non-square image:

{
  "error": {
    "message": "Image must be square (800x600 is not square)",
    "type": "invalid_request_error",
    "param": "image",
    "code": "image_not_square"
  }
}

Mask dimension mismatch:

{
  "error": {
    "message": "Mask dimensions (256x256) do not match image dimensions (512x512)",
    "type": "invalid_request_error",
    "param": "mask",
    "code": "dimension_mismatch"
  }
}

Unsupported model:

{
  "error": {
    "message": "Model 'dall-e-3' does not support image editing. Supported models: gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1, gpt-image-1-mini, gpt-image-1.5, dall-e-2, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro. Note: dall-e-3 does NOT support image editing.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "unsupported_model"
  }
}

Notes:

• Supported models: gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1, gpt-image-1-mini, gpt-image-1.5, dall-e-2, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, plus configured metadata aliases that resolve to one of these models or a Gemini image model
• DALL-E 3 does NOT support image editing via API
• Nano Banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro) routes to Gemini's native generateContent API using natural-language editing (mask is ignored if supplied, and n must be 1)
• Multiple input images can be uploaded by repeating image or image[] up to the model's input limit (16 for gpt-image-*, 14 for nano-banana / nano-banana-2 / nano-banana-2-lite / nano-banana-pro, 1 for dall-e-2)
• When no mask is provided, the entire image may be modified
• Request timeout uses the image generation timeout configuration

Image Variations¶

Generate variations of an existing image using Nano Banana (Gemini) or OpenAI's DALL-E 2 model.

POST /v1/images/variations
Content-Type: multipart/form-data

Form Fields: