Responses API

Use the R9S Responses endpoint for instruction-based, tool-capable, and stateful model calls.

The Responses API is useful when you want a single endpoint for text input, message arrays, instructions, tools, streaming, reasoning configuration, and optional response chaining.

Endpoint

POST /responses

Full URL:

https://gw.r9s.ai/v1/responses

When to use it

Use /responses when you want:

  • A top-level input field instead of chat messages.
  • A top-level instructions field for system behavior.
  • Tool definitions in the Responses flat tool format.
  • Optional previous_response_id chaining.
  • Background execution for long-running work.
  • Reasoning and truncation controls where supported by the model.

Use /chat/completions when you need maximum compatibility with existing OpenAI chat-completion client code.

Common request fields

Field Type Required Notes
model string Yes Model identifier
input string or array Yes Text input or message array
instructions string No System-level guidance
stream boolean No Enables streaming
max_output_tokens integer No Maximum generated tokens
temperature number No Controls randomness
top_p number No Nucleus sampling
tools array No Flat Responses tool definitions
tool_choice string No none, auto, or required
parallel_tool_calls boolean No Allows or limits parallel tool calls
previous_response_id string No Continue from a previous stored response
store boolean No Set false when response storage is not allowed
background boolean No Run long work asynchronously
reasoning object No Reasoning model configuration
truncation string No auto or disabled
metadata object No Custom tracking data

Simple text input

{
  "model": "gpt-4o-mini",
  "input": "Tell me a joke about programming.",
  "instructions": "You are a funny assistant.",
  "max_output_tokens": 500,
  "temperature": 0.7
}

Message array input

{
  "model": "gpt-4o-mini",
  "input": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "instructions": "You are a helpful assistant.",
  "max_output_tokens": 1000
}

Streaming with tools

{
  "model": "gpt-4o-mini",
  "input": [
    {
      "role": "user",
      "content": "Calculate 15% tip on an 85.50 bill and tell me the total."
    }
  ],
  "instructions": "You are a calculator assistant.",
  "stream": true,
  "tools": [
    {
      "type": "function",
      "name": "calculate",
      "description": "Perform a mathematical calculation",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string"
          }
        },
        "required": ["expression"]
      }
    }
  ],
  "max_output_tokens": 1000
}

JSON output

{
  "model": "gpt-4o-mini",
  "input": "Extract person information: Alice Chen is a software engineer in San Francisco.",
  "instructions": "Return only valid JSON.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "occupation": { "type": "string" },
          "location": { "type": "string" }
        },
        "required": ["name", "occupation", "location"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

Compatibility notes

  • The messages parameter is deprecated for this endpoint; use input.
  • Message array input should use basic fields such as role, content, and name.
  • Tool-call history fields such as tool_calls and tool_call_id are not part of the basic message array input.
  • Define tools at the top-level tools field.
  • Use store: false when your organization requires zero data retention behavior.
  • If truncation is disabled, requests that exceed the context window should fail instead of dropping early input.

Client example

curl https://gw.r9s.ai/v1/responses \
  -H "Authorization: Bearer $R9S_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Summarize the value of gateway routing.",
    "instructions": "Answer in two concise bullets."
  }'