Chat Completions

Endpoint

POST https://api.onerouter.app/v1/chat/completions

Quick Examples

Same API, every model. Choose your language:

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.onerouter.app/v1")
response = client.chat.completions.create(model="gpt-4o", messages=[{"role":"user","content":"Hello"}])
print(response.choices[0].message.content)

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.ONEROUTER_API_KEY, baseURL: 'https://api.onerouter.app/v1' });
const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });
console.log(response.choices[0].message.content);

curl -X POST "https://api.onerouter.app/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Request Body

Example Request & Response

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Response Fields

Understanding Token Usage

The usage object reports tokens consumed for billing:

• prompt_tokens — Tokens in your input messages (including system prompt, history, and any attached media converted to token equivalents)
• completion_tokens — Tokens generated by the model in the response
• total_tokens — Sum of prompt + completion tokens = what you're billed for

For multimodal inputs (images, audio), providers convert media to token equivalents. GPT-4o counts ~85 tokens for a low-res image and ~170+ for high-res. Your dashboard shows the final token count and cost per request.

Streaming (SSE)

Set stream: true to receive tokens in real-time as the model generates them. OneRouter uses standard Server-Sent Events (SSE) — fully compatible with the OpenAI streaming format.

Example

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.onerouter.app/v1")

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl -X POST "https://api.onerouter.app/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

SSE Chunk Format

Each chunk is a JSON object prefixed with data:. The stream ends with data: [DONE]:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Each chunk contains a delta object (not message). The content field may be empty or absent on the final chunk. The last chunk has finish_reason set and an empty delta.

Streaming with Tool Calls

When the model calls a function during streaming, tool call chunks arrive in the delta with tool_calls — the function name and arguments are streamed incrementally. Accumulate all chunks for a given tool_call_id to assemble the complete function call, then send back a role: "tool" message.

Tool / Function Calling

OneRouter supports OpenAI-compatible function calling across all capable models. Define your tools in the request, and models respond with structured JSON function calls that your code executes.

Defining Tools

Pass a tools array with function definitions. Each function needs a name, description, and JSON Schema parameters:

"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}]

Model Response with Tool Calls

When the model decides to call a function, the response includes tool_calls instead of text content:

{
  "role": "assistant",
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Paris\"}"
    }
  }]
}

Complete Tool Calling Flow

1. Send request with tools definitions
2. Receive tool_calls in the response — extract function name and arguments
3. Execute the function in your code (call your weather API, query your database, etc.)
4. Send results back as a message with role: "tool", referencing the tool_call_id
5. Model responds with a natural language answer incorporating the tool results

Supported Models

Tool calling is supported by: GPT-4o, GPT-4.1, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 2.5 Pro, Gemini 2.5 Flash, DeepSeek V3, Mistral Large 3, Llama 4, Qwen3, and more. Check the Models page for per-model capability details.

Vision / Image Input

For multimodal models like GPT-4o and Claude 4 Vision, include images as URLs or base64-encoded data in the content array:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }]
}

Supported image formats: PNG, JPEG, WebP, GIF (non-animated). Max image size varies by model — typically 20MB per image. For Claude models, PDF documents are also supported as visual input.

JSON Mode / Structured Output

Force the model to return valid JSON by setting response_format:

• JSON mode: {"type": "json_object"} — Model returns valid JSON. You must include the word "JSON" in your system prompt.
• Structured Output: {"type": "json_schema", "json_schema": {...}} — Model returns JSON matching your exact schema. Supported by GPT-4o and newer models.