OpenAI Compatible - Responses | Unisound Maas Platform

OpenAI Compatible - Responses

The platform provides an OpenAI Responses API-compatible interface. This page covers request parameters, response structure, and code examples.

POST/v1/responses

Compatibility notes and limits

This API aligns with the OpenAI Responses API specification for easier integration. Only documented parameters are handled normally; undefined parameters may be filtered or cause request errors. See the differences below.

Unsupported parameters: background, previous_response_id, store, context_management, and similar fields are not supported. Including them may be ignored or return an error.

Authorization

AuthorizationstringheaderRequired

HTTP: Bearer Auth

Security Scheme Type: http
HTTP Authorization Scheme: Bearer API_key, used to verify account information and can be viewed in Metered & Packs > API Key Management.

Request Header

Content-Typeenum<string>Default: application/jsonRequired

The media type of the request body. Set it to application/json to ensure the request data is JSON.

Available option: application/json

Request Bodyapplication/json

modelstringRequired

Model code. Available values:

Unisound Series: u2-flash, u2, u2-med, u2-radimed

DeepSeek Series: deepseek-v4-flash-0731, deepseek-v4-pro

Kimi Series: kimi-k2.5, kimi-k2.6, kimi-k3

GLM Series: glm-5.3, glm-5.2, glm-5.1, glm-5

MiniMax Series: MiniMax-M3, MiniMax-M2.5

Qwen (Tongyi Qianwen) Series: qwen3.8-flash, qwen3.7-plus, qwen3.7-max, qwen3.8-max, qwen3.6-plus, qwen3.6-flash, qwen3.6-35b-a3b

inputstring | arrayRequired

Model input. Supported formats:

string: plain text, e.g. "Hello".
array: ordered list of input items.

EasyInputMessageobjectOptional

Use role for message type and content for the payload.

rolestringRequired

Message role. Allowed values:

user: user message.
assistant: assistant message.
system: system message.

contentstring | arrayRequired

Message content. Use a string for plain text, or an array for structured content blocks.

When role is system, array items use input_text.
When role is user, array items may be input_text or input_image.
When role is assistant, array items use output_text.

typestringRequired

Content type. Allowed values:

input_text: text input.
input_image: image input (user role only).
output_text: assistant reply (assistant role only).

textstringOptional

Text content. Required when type is input_text or output_text.

image_urlstringOptional

Image URL or Base64 data URL. Required when type is input_image. Use a full Data URI for Base64, e.g. data:image/png;base64,....

detailstringOptional

Image detail level: auto / low / high.

typestringOptional

Optional. Fixed to message.

ResponseOutputMessageobjectOptional

Model output message object. You can pass a previous response output message item back into input for multi-turn chat. Unlike EasyInputMessage, it carries the full output shape (id, status, structured content).

typestringRequired

Fixed to message.

idstringRequired

Unique output message id from the previous response.

rolestringRequired

Fixed to assistant.

statusstringRequired

Message status: in_progress, completed, or incomplete.

contentarrayRequired

Content array of output_text objects.

typestringRequired

Fixed to output_text.

textstringRequired

Reply text.

Function CallobjectOptional

Structured instruction when the model decides to call an external tool.

typestringRequired

Fixed to function_call.

call_idstringRequired

Tool call id; must match the model-returned call_id.

namestringRequired

Tool function name.

argumentsstringRequired

Tool arguments as a JSON string.

idstringOptional

Unique Function Call id from the previous response.

statusstringOptional

Status: in_progress, completed, or incomplete.

Function Call OutputobjectOptional

Tool call result. Must immediately follow the corresponding function_call item in the message list, or the request fails.

typestringRequired

Fixed to function_call_output.

call_idstringRequired

Tool call id; must match the model-returned call_id.

outputstringRequired

Tool function execution result.

idstringOptional

Unique Function Call Output id.

statusstringOptional

Status: in_progress, completed, or incomplete.

ReasoningobjectOptional

Model reasoning content. You can pass a previous response output reasoning item back into input for multi-turn context.

typestringRequired

Fixed to reasoning.

idstringRequired

Unique reasoning item id from the previous response.

summaryarrayRequired

Reasoning summary content.

typestringRequired

Fixed to summary_text.

textstringRequired

Summary text.

statusstringOptional

Status: in_progress, completed, or incomplete.

instructionsstringOptional

System instructions inserted at the start of the context.

streambooleanOptionalDefault: false

Whether to reply in streaming mode.

false: return once after the model generates all content;
true: return incrementally while generating, and each partial result is returned as a data chunk. These chunks need to be read one by one in real time and concatenated into the full reply.

Setting it to true is recommended to improve reading experience and reduce timeout risk.

storebooleanOptional

Not supported. The response always has store: false.

max_output_tokensintegerOptional

Maximum output tokens (including reasoning tokens).

temperaturefloatOptional

Sampling temperature, used to control output diversity. A higher temperature makes the generated text more diverse; a lower temperature makes it more deterministic.

Value range: [0,2).

Default value of temperature: 1.0.

top_pfloatOptional

Nucleus sampling threshold that controls output diversity. It is recommended to use either this or temperature, not both.

Value range: (0, 1.0].

The default value is determined by the model.

toolsarrayOptional

Array of one or more tool objects for Function Calling. Each tool object directly includes type, name, description, and parameters (flat; do not nest a function object).

If tools is set and the model decides a tool call is needed, the response returns an output item with type of function_call (including call_id, name, and arguments). After execution, pass the result back in input as function_call_output.

typestringRequired

Tool type. Currently only function is supported.

namestringRequired

Tool name. Only letters, digits, underscores (_), and hyphens (-) are allowed, with a maximum of 64 tokens.

descriptionstringRequired

Tool description that helps the model decide when and how to call the tool.

parametersobjectOptionalDefault: {}

Tool parameter schema. Must be a valid JSON Schema.

If parameters is empty, the tool takes no arguments (e.g. a time lookup tool). Passing parameters is recommended to improve tool-call accuracy.

tool_choicestring | objectOptionalDefault: auto

Tool selection strategy. Set this when you need to force how tools are chosen for certain questions.

auto: the model decides whether to call a tool;
none: disallow any tool calls;
required: force a tool call (suitable when the tools list has only one tool);
{"type": "function", "name": "<tool_name>"}: force calling the specified tool.

When thinking is enabled (reasoning.effort is not none), forcing a specific tool is not supported.

parallel_tool_callsbooleanOptional

Whether to allow parallel tool calls.

reasoningobjectOptional

Controls the model thinking strength.

effortstringOptional

Controls the model's reasoning effort. Supported values and defaults vary by model.

Model	Default	Supported levels	Mapping of other levels
`deepseek-v4-pro`, `glm-5.2`, `glm-5.1`, `glm-5`	`high`	`high`, `max`	`low` and `medium` map to `high`; `xhigh` maps to `max`
`deepseek-v4-flash-0731`	`high`	`max`, `high`, `low`	`medium` maps to `high`; `xhigh` maps to `high`
`kimi-k3`, `glm-5.3`, `glm-5.3-flash`	`max`	`max`, `high`, `low`	—
`qwen3.8-max`, `qwen3.8-flash`	`xhigh`	`xhigh`, `medium`, `low`	`max` and `high` map to `xhigh`; `minimal` maps to `low`; `none` disables thinking
`u2-med`	—	`none`, `low`, `medium`, `high`	`minimal` maps to `low`; `xhigh` and `max` map to `high`
`MiniMax-M3`	—	`none` and other levels	`none`: disable thinking; other values enable adaptive thinking without adjusting thinking depth

kimi-k3, glm-5.3, and glm-5.3-flash always enable thinking. Setting reasoning.effort to none is not supported and causes the API request to fail.

Values other than the supported options and mapped values above will cause an error.

reasoning.effort is a standard OpenAI parameter. When using the Python SDK, pass reasoning={"effort": "high"} directly; do not put it in extra_body.

textobjectOptional

Controls the response content format.

formatobjectOptional

Output format configuration.

typestringRequired

text.format.type response content format. Allowed values:

text: plain text reply;
json_object: a standard JSON string.

If set to json_object, instructions or system/user text in input must include the keyword "JSON" (case-insensitive), otherwise the API returns an error.

For models that support structured output only in non-thinking mode, do not set text.format.type to json_object when thinking is enabled (reasoning.effort is not none), otherwise the API returns an error.

Qwen Series: qwen3.7-plus, qwen3.7-max, qwen3.8-max, qwen3.8-flash

Qwen Series (non-thinking): qwen3.6-plus, qwen3.6-flash, qwen3.6-35b-a3b

DeepSeek Series: deepseek-v4-flash-0731, deepseek-v4-pro

Kimi Series: kimi-k2.5, kimi-k2.6, kimi-k3

GLM Series: glm-5.1

GLM Series (non-thinking): glm-5

top_logprobsintegerOptionalDefault: 0

An integer specifying how many of the most likely tokens to return at each generation step.

Range: [0,5].

Response structure (non-streaming, HTTP 200)

idstring

Top-level object is always "response".

Unique id of this response.

objectstring

Object type, fixed to response.

created_atinteger

Unix timestamp (seconds) of this request.

statusstring

Response generation status. Enum values:

completed: finished successfully.
failed: generation failed.
in_progress: generating.
queued: queued.
incomplete: incomplete generation.

modelstring

Model id used to generate the response.

outputarray

Array of model output items. Item types and order depend on the model response; commonly message (final reply). May also include reasoning, function_call, etc.

To read text: iterate output, for items with type === "message", concatenate text from content blocks where type === "output_text" (or use SDK output_text).

assistant textobject

Message-type output item containing the model’s final reply.

typestring

Output item type, fixed to message.

idstring

Unique output item id.

rolestring

Message role, fixed to assistant.

statusstring

Output item status, commonly completed or in_progress.

contentarray

Message content array. Present when type is message.

typestring

Content type, fixed to output_text.

textstring

Model-generated text.

usageobject | null

Token usage for this request.

input_tokensinteger

Input token count (including cache hits); same semantics as Chat prompt_tokens.

input_tokens_detailsobject

Fine-grained breakdown of input tokens.

cached_tokensinteger

Cached input tokens; a subset of input_tokens (already included in input_tokens—do not subtract again when displaying totals).

output_tokensinteger

Output token count (may include reasoning tokens).

output_tokens_detailsobject

Fine-grained breakdown of output tokens.

reasoning_tokensinteger

Reasoning tokens; a subset of output_tokens (already included in output_tokens; billing follows the actual invoice).

total_tokensinteger

Total tokens consumed, usually input_tokens + output_tokens.

Example: input_tokens=1000, cached_tokens=600, output_tokens=200 (with reasoning_tokens=50) → total_tokens=1200 (do not display input_tokens as 400 or output_tokens as 150).

errorobject | null

Error object when generation fails; null on success.

incomplete_detailsobject | null

Reason details when status is incomplete.

storeboolean

Whether this response is persisted. Store is unsupported; always false.

Error response (HTTP 4xx/5xx or error in body)

error.messagestring

OpenAI style:

Error description.

error.typestring

e.g. invalid_request_error.

error.codestring

Business error code (optional).

error.paramstring

Related parameter name (optional).

Streaming (`stream=true`)

The response is SSE; parse event: / data: line by line.
Common text delta event: `response.output_text.delta`; `data` includes a `delta` field.
Common terminal events: `response.completed` / `response.incomplete` / `response.failed`; terminal `data` includes the full `response` and `usage` (same field semantics as non-streaming).
See the full event list: OpenAI Responses streaming events.

Streaming fragment example

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_example","delta":"你好"}

Error example (missing model)

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_parameter"
  }
}

Request example

curl -X POST https://maas-api.unisound.com/v1/responses \
 -H "Authorization: Bearer <api_key>" \
 -H "Content-Type: application/json" \
 -d '{
     "model": "u2-flash",
     "input": "Hello",
     "max_output_tokens": 1024,
     "store": false
 }'

Response example (non-streaming)

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1789459200,
  "status": "completed",
  "model": "<model-id>",
  "store": false,
  "output": [{
    "id": "msg_example",
    "type": "message",
    "role": "assistant",
    "status": "completed",
    "content": [{
      "type": "output_text",
      "text": "你好，有什么可以帮你？",
      "annotations": [],
      "logprobs": []
    }]
  }],
  "usage": {
    "input_tokens": 1000,
    "input_tokens_details": {"cached_tokens": 600},
    "output_tokens": 200,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 1200
  },
  "error": null,
  "incomplete_details": null
}