Chat (OpenAI-Compatible)

POST /v1/chat/completions — OpenAI-compatible chat with streaming, tool calls and multimodal input.

This endpoint uses the OpenAI Chat Completions-compatible format and works with GPT, Claude, Gemini, and other models whose model-list entry supports the OpenAI chat endpoint. Exact capabilities depend on the selected model and its upstream provider.

Endpoint

POST https://api.tokenhub.belivestudios.com/v1/chat/completions

Request Example

curl https://api.tokenhub.belivestudios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-belive-studios-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Introduce BeLive Studio in one sentence"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

Python SDK

Use the official OpenAI SDK — just swap base_url and api_key:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenhub.belivestudios.com/v1",
    api_key="sk-your-belive-studios-key",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Streaming

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Write a short poem"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Common Parameters

Parameter	Type	Description
`model`	string	Required. Model ID, exactly as listed in the console
`messages`	array	Required. Conversation messages
`temperature`	number	Sampling temperature, usually 0–2; use only when supported by the model
`max_completion_tokens`	number	OpenAI's recommended output-token limit, including visible output and reasoning tokens
`max_tokens`	number	Compatibility field that also limits output; prefer `max_completion_tokens` for new integrations
`stream`	boolean	Stream output (SSE)
`tools`	array	Function-calling tool definitions; use only when supported by the model
`tool_choice`	string \| object	Controls whether and how the model calls tools
`response_format`	object	Structured output, e.g. `{"type": "json_object"}`; use only when supported
`reasoning_effort`	string	Reasoning effort; available values and compatibility depend on the model

Model compatibility

Chat, streaming, image input, tool calls, structured output, and sampling parameters can vary by model. Check the endpoint types in the model list and send only parameters supported by the selected model.

Gemini reasoning controls

On /v1/chat/completions, use reasoning_effort as the preferred cross-provider control. Gemini requests accept none, minimal, low, medium, and high, subject to the model-specific rules below:

Model ID	`reasoning_effort` behavior
`gemini-3.5-flash`	`none` sends `thinkingBudget: 0`; other supported values are converted to a proportional thinking budget
`gemini-3.6-flash`	`none` sends `thinkingBudget: 0`; other supported values are converted to a proportional thinking budget
`gemini-3.1-pro-preview`	`none` sends `thinkingBudget: 0`; other supported values are converted to a proportional thinking budget
`gemini-3.7-flash`	`low`, `medium`, and `high` map to Gemini `thinkingLevel`; `none` and `minimal` return HTTP 400 because this model cannot reliably disable thinking and does not support `MINIMAL`

For example, the following request lowers the thinking level of gemini-3.7-flash:

{
  "model": "gemini-3.7-flash",
  "messages": [{"role": "user", "content": "Analyze this problem"}],
  "reasoning_effort": "low",
  "max_completion_tokens": 2000
}

To disable thinking on a model verified to support it:

{
  "model": "gemini-3.5-flash",
  "messages": [{"role": "user", "content": "Answer directly"}],
  "reasoning_effort": "none",
  "max_completion_tokens": 2000
}

For direct access to Gemini-native controls, use extra_body.google.thinking_config:

{
  "model": "gemini-3.7-flash",
  "messages": [{"role": "user", "content": "Analyze this problem"}],
  "extra_body": {
    "google": {
      "thinking_config": {
        "thinking_level": "low",
        "include_thoughts": true
      }
    }
  }
}

Do not combine reasoning_effort with extra_body.google.thinking_config; the API returns HTTP 400 for conflicting controls. The aliases thinking, top-level thinking_budget, and reasoning are not supported for Gemini Chat Completions and also return HTTP 400 instead of being silently ignored.

Important note

For models with thinking or reasoning enabled, both max_tokens (the compatibility field) and max_completion_tokens limit the output budget, which is shared by internal reasoning tokens and the final visible response. If the limit is too low, the API may return HTTP 200 while choices[0].message.content is empty and finish_reason is "length"; this does not mean that a displayable response was generated. Use only one of the two limit parameters per request and leave enough room for reasoning models.

For example, the following request may reproduce the “HTTP 200 + empty content” behavior:

{
  "model": "gemini-3.5-flash",
  "messages": [{"role": "user", "content": "Introduce BeLive Studio in one sentence"}],
  "max_tokens": 10,
  "stream": false
}

Do not judge success from the HTTP status alone. Check both choices[0].message.content and choices[0].finish_reason. If the content is empty and finish_reason is "length", increase the output-limit parameter used by the request and retry, then inspect usage.completion_tokens_details.reasoning_tokens. The platform does not automatically add response budget when the value is too small, and there is no single minimum that applies to every model.

Response example and fields

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1788160065,
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Test succeeded"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 5,
    "total_tokens": 16,
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

Field	Description
`id` / `object` / `created` / `model`	Request identifier, object type, creation time, and actual model used
`choices[].message.content`	Generated text; it may be `null` for a tool call
`choices[].message.tool_calls`	Tools requested by the model; present only when a tool is called
`choices[].finish_reason`	Common values: `stop`, `length`, `tool_calls`, and `content_filter`
`usage.prompt_tokens`	Input-token count
`usage.completion_tokens`	Output-token count, which may include reasoning consumption
`usage.total_tokens`	Total input and output tokens
`usage.completion_tokens_details.reasoning_tokens`	Reasoning-token count; read it only when the response provides this detail

Multimodal Input

Models that support image input accept a URL or Base64 data URL through image_url. The following is a complete request body:

The server must be able to download a remote image URL directly without a signed-in browser session or temporary browser permissions.

{
  "model": "gemini-3.5-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}}
    ]
  }],
  "stream": false
}

Function Calling

{
  "model": "gpt-5.6-sol",
  "messages": [{"role": "user", "content": "What's the weather in Hangzhou? Call the tool to check."}],
  "reasoning_effort": "none",
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather of a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

For this example model, set reasoning_effort to "none" when using Function Calling through Chat Completions. When the model requests a tool, finish_reason is "tool_calls", and message.tool_calls contains the function name, arguments, and tool-call ID. After executing the function, preserve the assistant message and append the matching tool result:

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [{
      "id": "call_example",
      "type": "function",
      "function": {"name": "get_weather", "arguments": "{\"city\":\"Hangzhou\"}"}
    }]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example",
    "content": "{\"city\":\"Hangzhou\",\"temperature\":\"26°C\",\"condition\":\"sunny\"}"
  }
]

Append these two messages to the original messages and send another request with the same tools so the model can produce the final answer. Function arguments is a JSON string; parse and validate it before execution.

Chat (OpenAI-Compatible)

On this page