Chat Completions

Create chat completions through the R9S OpenAI-compatible gateway endpoint.

Use chat completions for conversational applications, coding assistants, support agents, structured JSON responses, tool calling, and multimodal prompts that follow the OpenAI chat format.

Endpoint

POST /chat/completions

Full URL:

https://gw.r9s.ai/v1/chat/completions

Common request fields

Field Type Required Notes
model string Yes Model identifier available to your account
messages array Yes Ordered conversation messages
stream boolean No Enables streaming chunks
temperature number No Controls randomness
top_p number No Nucleus sampling
max_tokens integer No Maximum generated tokens for compatible models
max_completion_tokens integer No Alternate output-token limit for newer model families
response_format object No JSON mode or JSON schema output
tools array No Function tools the model can call
tool_choice string or object No none, auto, required, or a forced function
parallel_tool_calls boolean No Allows multiple tool calls when supported
reasoning_effort string No low, medium, or high for reasoning models
metadata object No Custom tracking metadata
user string No End-user identifier for abuse monitoring and analytics

Basic request

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ]
}

Request with system message

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise technical assistant."
    },
    {
      "role": "user",
      "content": "Explain gateway fallback in two bullets."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 200
}

Streaming request

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Write a short deployment checklist."
    }
  ],
  "stream": true
}

Use streaming for interactive UI and agent experiences. Keep non-streaming mode for batch jobs, strict JSON parsing, or requests that require features unavailable with streaming.

Structured JSON output

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Create a deployment status object for a healthy gateway rollout."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "deployment_status",
      "schema": {
        "type": "object",
        "properties": {
          "state": { "type": "string" },
          "risk": { "type": "string" },
          "next_step": { "type": "string" }
        },
        "required": ["state", "risk", "next_step"]
      }
    }
  }
}

Tool calling

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in San Francisco?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather in a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string"
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

When the model returns a tool call, execute the tool in your application and send the result back as a tool message with the matching tool_call_id.

Vision input

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}

Vision support depends on the selected model. Check /models and the R9S console before shipping multimodal traffic.

Response fields

Typical chat responses include:

Field Description
id Response identifier
object Response object type
created Creation timestamp
model Model that produced the response
choices Generated messages or deltas
usage Prompt, completion, and total token counts when available

For streaming, parse server-sent events until the final completion signal.