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

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

Minimal request

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

Streaming request

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

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

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

Image generation tool

Keys with image generation enabled can request the Responses image_generation tool from Codex-style and OpenAI-compatible clients. Use a GPT/Codex text model as the main model, attach an image_generation tool, and set the tool model to an image model such as gpt-image-2.

{
  "model": "gpt-5.4",
  "input": "Create a clean product illustration of a teal API dashboard.",
  "tools": [
    {
      "type": "image_generation",
      "model": "gpt-image-2",
      "size": "1024x1024",
      "output_format": "png"
    }
  ],
  "tool_choice": { "type": "image_generation" },
  "stream": false
}

Non-streaming responses include an image_generation_call item in output. Streaming calls emit Responses-compatible server-sent events, ending with response.completed.

Reference images through Responses

Responses image generation can also use reference images. Put input_image items in the user message content and provide image_url values. Quotaflow accepts HTTPS image URLs and data URLs here, then routes the request through the same image editing pool used by /images/edits. Raw GPT/Codex Responses requests that include input_image without an image_generation tool are rejected with 400 invalid_request_error instead of being retried on a text-only route.

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Place this product into a clean studio scene. Keep the label readable." },
        { "type": "input_image", "image_url": "https://example.com/product.png" }
      ]
    }
  ],
  "tools": [
    {
      "type": "image_generation",
      "model": "gpt-image-2",
      "size": "1536x1024",
      "quality": "high",
      "input_fidelity": "high",
      "output_format": "png"
    }
  ],
  "tool_choice": { "type": "image_generation" },
  "stream": false
}

For browser or backend file uploads, multiple source images, or masks, use the dedicated Images API with /images/edits. Responses input_image.file_id is not supported yet; use input_image.image_url, a data URL, or /images/edits multipart uploads. For Codex Desktop one-sentence image prompts, follow the GPT Image 2 Codex Desktop setup so the desktop agent saves and displays the returned PNG through your Quotaflow key.

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.