Responses API

When to use this page

Use this page for Codex-style agent calls, tool-capable workloads, and modern OpenAI-compatible clients that natively send Responses-shaped requests. Keys enabled for Claude-compatible models can also use Claude model ids on this OpenAI-compatible endpoint while receiving Responses-shaped output. Gemini text model ids are accepted here too, with or without the google/ prefix — see the stateless note below. GLM and Kimi model ids are chat-only on Quotaflow and should use /chat/completions; Responses requests for those ids are rejected clearly instead of being remapped to another model.

Gemini on this endpoint

Gemini text ids (gemini-3.8-flash, gemini-3.7-flash, gemini-3.1-pro-preview, and the other ids your discovery endpoint returns) are accepted on /responses as well as on /chat/completions. This endpoint is stateless for them: send the whole turn in input on every request, and store: true, previous_response_id, conversation, prompt and background return 400 invalid_request_error, because Quotaflow keeps no response store to read them back from. Reasoning items you received on a previous turn should be replayed unchanged — Quotaflow passes a Gemini transcript's reasoning state back to the upstream untouched.

How this endpoint serves Gemini. Both OpenAI-shaped endpoints serve the three ids above from 2026-09-22. /chat/completions is served directly by cells on Google's own OpenAI-compatible endpoint (measured — a same-day three-turn conversation on gemini-3.1-pro-preview answered 200 with the vendor's own usage bytes and its thought_signature passed through). /responses is served by projection onto those same cells: Google's OpenAI-compatible endpoint exposes chat/completions only (its /responses path is a 404) and no relay Quotaflow buys from serves Gemini on a Responses wire, so Quotaflow rewrites your Responses request into a Chat Completions request at the edge, runs it on the same cells with the same admission and billing, and rewrites the answer back into a Responses object or event stream. What that means for you: instructions becomes the system message; input messages, function_call and function_call_output items become chat messages; max_output_tokens, reasoning.effort, temperature, top_p, text.format and function tools map onto their chat spellings, and the projected request is admitted exactly as a /chat/completions request is — today that means a Gemini request declaring tools or carrying image input is refused 400 on both OpenAI-shaped endpoints, because no cell has a measured price for those shapes yet; usage reports input_tokens/output_tokens and carries cached_tokens or reasoning_tokens only when the vendor reported them. Hosted tools (web_search, file_search, code_interpreter) and file inputs have no chat-wire equivalent on this line and return 400 invalid_request_error with param naming the field; image_generation is refused 400 on this endpoint for every model, before the projection, with a message that points at /v1/images and no param. Gemini's reasoning state travels as a type: "reasoning" output item whose encrypted_content is the model's thought signature, placed right after the message or function_call item it belongs to; replay your previous turn's output items unchanged as the next turn's input and the signature reaches the model exactly as it was minted. The model dossiers' per-capability tables describe the cells, so they list the gemini.chat.* capabilities; there is no gemini.responses.* capability because there is no cell on that wire.

If your client sends Chat Completions messages and tools, use /chat/completions instead. Quotaflow keeps Chat Completions and Responses as separate protocol surfaces so fallback and streaming parsers stay consistent.

Endpoint

POST https://api.quotaflow.ai/openai/v1/responses

Required output bound

max_output_tokens is required on every /responses request. It bounds generated output tokens including reasoning tokens, and it is the value the request is priced against before a vendor is selected. A request without it is rejected with 400 invalid_request_error. Quotaflow does not substitute a vendor default, because an invented bound would reserve against a price the request never declared.

Chat Completions bounds are not interchangeable here. max_completion_tokens and max_tokens are not part of the Responses request contract and are rejected on this surface; use max_completion_tokens on /chat/completions instead.

Refused request shapes

For GPT/Codex models, the following are refused at admission with 400 invalid_request_error rather than routed, because none of them carries a bounded price before the upstream call:

• Image input parts, file or document input parts, and audio input parts.
• Hosted tools, meaning tools the upstream executes on your behalf inside the request: web_search (including web_search_2025_08_26, web_search_preview, and web_search_preview_2025_03_11), file_search, mcp, code_interpreter, and image_generation.

Client-executed tools are unaffected. function, custom, and local_shell remain accepted, including the gpt-5.6 tool support described below.

Minimal request

{
  "model": "gpt-5.5",
  "input": "Write a concise deployment checklist.",
  "stream": false,
  "max_output_tokens": 512
}

Streaming request

{
  "model": "gpt-5.5",
  "input": "Explain this repository structure.",
  "stream": true,
  "max_output_tokens": 1024
}

Curl example

curl https://api.quotaflow.ai/openai/v1/responses \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-session-id: repo-agent-123" \
  -d '{
    "model": "gpt-5.5",
    "input": "Summarize the change in one paragraph.",
    "stream": false,
    "max_output_tokens": 512
  }'

Codex-style agents

If enabled for your API key, Quotaflow accepts tool-capable Codex-style requests while preserving the OpenAI-compatible request shape.

For Claude-compatible claude-sonnet-5, claude-opus-4-8, and claude-opus-4-7, omit non-default temperature, top_p, and top_k from Responses requests. Those adaptive-only Claude models use adaptive behavior instead of explicit sampling controls. Quotaflow strips the fields where possible; use reasoning.effort when your client needs a depth hint.

Do not send Claude-style or Gemini-style top-level thinking to the OpenAI-compatible Responses endpoint. For GPT/Codex Responses requests, use reasoning.effort when the selected model supports reasoning controls. Unsupported parameter families return a clear 400 invalid_request_error and are not retried on another execution path, because they are request contract errors rather than service availability errors.

GPT-5.6 tools

gpt-5.6 supports function and custom tools on /responses, including streamed tool calls, strict function schemas, and agent-sized tool sets. Quotaflow routes each request only to supply with matching provider-scoped evidence; if no verified candidate remains, the request fails closed instead of silently dropping tools or switching models. Tool use, reasoning summaries, and encrypted reasoning items are separate capabilities and are not inferred from one another.

Image generation

The current public Responses contract does not expose image_generation. Use the dedicated synchronous Images API for generation. Image edits, reference images, multipart uploads, and masks remain unavailable. Requests that require an unavailable image capability fail closed rather than falling back to an older image route.

Unsupported public HTTP fields

The public HTTP Responses endpoint does not support previous_response_id continuation or background: true asynchronous execution. Requests that include those fields are rejected with invalid_request_error instead of being sent down a single execution path without fallback. Use a fresh Responses request on HTTP, or use the dedicated WebSocket continuation surface when available for your integration.

Response shape

Quotaflow returns OpenAI-compatible JSON for non-streaming calls and server-sent events for streaming calls.