Chat Completions

POST /v1/chat/completions

Chat completions is the core endpoint. It supports:

• Multi-turn conversations
• Streaming output (SSE)
• Image understanding (multimodal messages)
• Function / tool calling
• Forced JSON output

Request parameters

Required

Parameter	Type	Description
model	string	Model ID, obtainable from /v1/models
messages	array	The message array, see below

Common optional parameters

Parameter	Type	Default	Description
stream	boolean	false	Whether to stream the response as SSE
stream_options	object	—	Streaming options, e.g. {"include_usage": true} to return usage in the final chunk
temperature	number	1	Sampling temperature 0–2; higher is more random
top_p	number	1	Nucleus sampling threshold; tune either this or temperature
max_tokens	integer	—	Maximum number of tokens in the reply
stop	string / array	—	Stop sequences, up to 4
tools	array	—	List of tool/function definitions
tool_choice	string / object	—	Tool selection strategy (auto / none / a specific tool)
response_format	object	—	e.g. {"type": "json_object"} to force JSON output

messages format

Each message is an object whose role is one of:

role	Description
system	System prompt defining the assistant's role and behavior
user	User message
assistant	The assistant's previous replies (for multi-turn)
tool	The result returned from a tool call

content can be a string, or an array of multimodal content (text + images).

Basic example

curl https://api.idreame.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a professional coding assistant."},
      {"role": "user",   "content": "Write a quicksort in Python."}
    ],
    "temperature": 0.7
  }'

Response example

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752600000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def quick_sort(arr):\n    if len(arr) <= 1:\n        return arr\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 120,
    "total_tokens": 148
  }
}

Streaming

With "stream": true, the response is returned as Server-Sent Events. Each line starts with data:, incremental content is in choices[0].delta.content, and the stream ends with data: [DONE]:

curl https://api.idreame.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hi"}],
    "stream": true
  }'

data: {"id":"chatcmpl-abc","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"He"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"llo!"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Python streaming example:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.idreame.ai/v1",
    api_key="sk-xxxxxxxx",
)

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing in 100 words"}],
    stream=True,
)

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

Image understanding (multimodal)

Models that support image understanding (such as gpt-4o, claude-sonnet-5) accept images in content:

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

Base64-encoded images are also supported:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
  }
}

Function / tool calling

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "What time is it in Beijing?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_time",
        "description": "Get the current time for a given city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Forced JSON output

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You must respond in JSON format."},
    {"role": "user",   "content": "Give me a sample user object with name and age fields."}
  ],
  "response_format": {"type": "json_object"}
}

WARNING

When using response_format: json_object, the system prompt must explicitly mention JSON, otherwise some models may return an error.