OpenAI Chat Format (Chat Completions)

Official Documentation

OpenAI Chat

📝 Introduction

Given a list of messages comprising a conversation, the model returns a response. This is the most widely compatible format — GPT, Claude, Gemini, DeepSeek, GLM, Kimi, Qwen, Grok and all other chat models on the gateway can be called through it.

📮 Endpoint

POST /v1/chat/completions

Authentication

Include your API key in the request headers:

Authorization: Bearer $WS_API_KEY

💡 Request Examples

Basic Text Chat ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Response Example:

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29
  }
}

Streaming Response ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Streaming Response Example (server-sent events):

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

Image Analysis (Vision) ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/photo.jpg"}
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

image_url.url accepts a public URL or base64 data (data:image/jpeg;base64,...).

Function Calling ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "What is the weather like in Dubai today?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather for a specified location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name, e.g. Dubai"},
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Response Example:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\"location\": \"Dubai\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Using Official SDKs

Any OpenAI-compatible SDK works — just point base_url at the gateway:

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",                     # your WS API key
    base_url="http://baseurl/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

📋 Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID, see Model Catalog
messages	array	Yes	Conversation messages. Roles: system / developer, user, assistant, tool
stream	boolean	No	true streams the response via server-sent events. Default false
stream_options	object	No	{"include_usage": true} appends a final chunk with token usage when streaming
temperature	number	No	Sampling temperature 0–2. Default 1. Higher = more random
top_p	number	No	Nucleus sampling. Alternative to temperature; don't change both
max_completion_tokens	integer	No	Upper limit of generated tokens (including reasoning tokens)
max_tokens	integer	No	Deprecated alias of max_completion_tokens, still accepted
stop	string / array	No	Up to 4 stop sequences
n	integer	No	Number of choices to generate. Default 1
presence_penalty	number	No	-2.0–2.0. Positive values encourage new topics
frequency_penalty	number	No	-2.0–2.0. Positive values reduce repetition
logprobs / top_logprobs	boolean / integer	No	Return token log probabilities
response_format	object	No	{"type":"json_object"} or {"type":"json_schema","json_schema":{...}} for structured output
seed	integer	No	Best-effort deterministic sampling
tools	array	No	Function definitions the model may call (up to 128)
tool_choice	string / object	No	none / auto / required or force a specific function
parallel_tool_calls	boolean	No	Allow parallel function calls. Default true
reasoning_effort	string	No	For reasoning models: low / medium / high
user	string	No	End-user identifier for abuse monitoring

📥 Response Fields

Field	Type	Description
id	string	Unique identifier of the completion
object	string	chat.completion, or chat.completion.chunk when streaming
created	integer	Unix timestamp of creation
model	string	Model used
choices	array	Generated choices. Each contains index, message (role, content, tool_calls, refusal) and finish_reason
choices[].finish_reason	string	stop (natural end), length (token limit), tool_calls (model called a tool), content_filter
usage	object	prompt_tokens, completion_tokens, total_tokens, plus detail breakdowns (cached_tokens, reasoning_tokens, ...)