文本生成（OpenAI API兼容）

开发指南 API参考

模型价格模型发布

通过兼容 OpenAI 格式的 Chat API 调用模型。

POST/v1/chat/completions

授权

Authorizationstringheader必填

HTTP: Bearer Auth

Security Scheme Type: http
HTTP Authorization Scheme: Bearer API_key，用于验证账户信息，可在项目管理>API Key中查看。

请求头

Content-Typeenum<string>默认值: application/json必填

请求体的媒介类型，请设置为 application/json，确保请求数据的格式为 JSON

可用选项: application/json

请求体application/json

modelstring必填

模型名称。支持的模型：u2-preview。

messagesarray必填

传递给大模型的上下文，按对话顺序排列。

System Messageobject选填

系统消息，用于设定大模型的角色、语气、任务目标或约束条件等。一般放在messages数组的第一位。

contentstring | array必填

系统指令，用于明确模型的角色、行为规范、回答风格和任务约束等。

typestring必填

内容类型，仅支持固定值text。

textstring必填

具体文本内容。

rolestring必填

系统消息的角色，固定为system。

User Messageobject必填

用户消息，用于向模型传递问题、指令或上下文等。

contentstring | array必填

消息内容。

typestring必填

内容类型，仅支持固定值text。

textstring必填

具体文本内容。

rolestring必填

用户消息的角色，固定为user。

Assistant Messageobject选填

模型的回复。通常用于在多轮对话中作为上下文回传给模型。

contentstring | array选填

模型回复的文本内容。包含tool_calls时，content可以为空；否则content为必选。

typestring必填

内容类型，仅支持固定值text。

textstring必填

具体文本内容。

reasoning_contentstring选填

模型的思维链内容。

rolestring必填

助手消息的角色，固定为assistant。

tool_callsarray选填

发起 Function Calling 后，返回的工具与入参信息，包含一个或多个对象。由上一轮模型响应的tool_calls字段获得。

idstring必填

工具响应的ID。

typestring必填

工具类型，当前只支持设为function。

functionobject必填

工具与入参信息。

namestring必填

工具名称。

argumentsstring必填

入参信息，为JSON格式字符串。

indexinteger必填

当前工具信息在tool_calls数组中的索引。

Tool Messageobject选填

工具的输出信息。

contentstring | array必填

工具函数的输出内容，若为结构化数据需序列化为字符串。

typestring必填

内容类型，仅支持固定值text。

textstring必填

具体文本内容。

rolestring必填

固定为tool。

tool_call_idstring必填

发起 Function Calling 后返回的 id，通过completion.choices[0].message.tool_calls[$index].id获取，用于标记 Tool Message 对应的工具。

streamboolean选填默认值: false

是否以流式输出方式回复。

false：模型生成全部内容后一次性返回；
true：边生成边输出，每生成一部分内容即返回一个数据块（chunk）。需实时逐个读取这些块以拼接完整回复。

推荐设置为true，可提升阅读体验并降低超时风险。

stream_optionsobject选填

流式输出的配置项，仅在 stream 为 true 时生效。

include_usageboolean选填默认值: false

是否在响应的最后一个数据块包含Token消耗信息。

true：包含；
false：不包含。

流式输出时，Token 消耗信息仅可出现在响应的最后一个数据块。

temperaturefloat选填

采样温度，控制模型生成文本的多样性。temperature越高，生成的文本更多样，反之，生成的文本更确定。

取值范围：[0,2)。

temperature默认值：1.0。

top_kinteger选填

指定生成过程中用于采样的候选 Token 数量。值越大，输出越随机；值越小，输出越确定。取值必须为大于或等于 0 的整数。

top_k默认值：40。

该参数非OpenAI标准参数。通过 Python SDK调用时，请放入 extra_body 对象中。配置方式为：extra_body={"top_k":xxx}。

max_tokensinteger选填

用于限制模型输出的最大 Token 数。若生成内容超过此值，生成将提前停止，且返回的finish_reason为length。

适用于需控制输出长度的场景，如生成摘要、关键词，或用于降低成本、缩短响应时间。

触发 max_tokens 时，响应的 finish_reason 字段为 length。

max_tokens不限制思考模型思维链的长度。

thinkingobject选填

是否开启思考模式。u2-preview默认开启思考，不支持关闭。

typestring必填

可选值：enabled（开启思考模式）、disabled（关闭思考模式）。

该参数非OpenAI标准参数。通过 Python SDK调用时，请放入 extra_body 对象中。配置方式为：extra_body={"thinking": "{"type":xxx}"}。

toolsarray选填

包含一个或多个工具对象的数组，供模型在 Function Calling 中调用。

设置 tools 且模型判断需要调用工具时，响应会通过 tool_calls 返回工具信息。

typestring必填

工具类型，当前仅支持设为function。

functionobject必填

namestring必填

工具名称。仅允许字母、数字、下划线（_）和短划线（-），最长 64 个 Token。

descriptionstring必填

工具描述信息，帮助模型判断何时以及如何调用该工具。

parametersobject选填默认值: {}

工具的参数描述，需要是一个合法的JSON Schema。

若parameters参数为空，表示该工具没有入参（如时间查询工具）。为提高工具调用的准确性，建议传入 parameters。

chat响应对象（非流式输出）

idstring

本次调用的唯一标识符。

choicesarray

模型生成内容的数组。

finish_reasonstring

模型停止生成的原因。有三种情况：

触发输入参数中的stop参数，或自然停止输出时为stop；
生成长度过长而结束为length；
需要调用工具而结束为tool_calls。

indexinteger

当前对象在choices数组中的索引。

messageobject

模型输出的消息。

contentstring

模型的回复内容。

reasoning_contentstring

模型的思维链内容。

rolestring

消息的角色，固定为assistant。

tool_callsarray

在发起 Function Calling后，模型生成的工具与入参信息。

idstring

本次工具响应的唯一标识符。

typestring

工具类型，当前只支持function。

functionobject

工具信息。

namestring

工具名称。

argumentsstring

入参信息，为JSON格式字符串。

由于大模型响应有一定随机性，输出的入参信息可能不符合函数签名。请在调用前校验参数有效性。

createdinteger

请求创建时的 Unix 时间戳（秒）。

modelstring

本次请求使用的模型。

objectstring

始终为chat.completion。

service_tierstring

该参数当前固定为null。

system_fingerprintstring

该参数当前固定为null。

usageobject

本次请求的 Token 消耗信息。

completion_tokensinteger

模型输出的 Token 数。

prompt_tokensinteger

输入的 Token 数。

total_tokensinteger

消耗的总 Token 数，为prompt_tokens与completion_tokens的总和。

chat响应chunk对象（流式输出）

idstring

本次调用的唯一标识符。每个chunk对象有相同的 id。

choicesarray

模型生成内容的数组，可包含一个或多个对象。若设置include_usage参数为true，则choices在最后一个chunk中为空数组。

deltaobject

请求的增量对象。

contentstring

增量消息内容。

reasoning_contentstring

增量思维链内容。

rolestring

增量消息对象的角色，只在第一个chunk中有值。

tool_callsarray

在发起 Function Calling后，模型生成的工具与入参信息。

indexinteger

当前工具在tool_calls数组中的索引。

idstring

本次工具响应的唯一标识符。

functionobject

被调用的工具信息。

argumentsstring

增量的入参信息，所有chunk的arguments拼接后为完整的入参。

由于大模型响应有一定随机性，输出的入参信息可能不符合函数签名。请在调用前校验参数有效性。

namestring

工具名称，只在第一个chunk中有值。

typestring

工具类型，当前只支持function。

finish_reasonstring

模型停止生成的原因。有四种情况：

因触发输入参数中的stop参数，或自然停止输出时为stop；
生成未结束时为null；
生成长度过长而结束为length；
需要调用工具而结束为tool_calls。

indexinteger

当前响应在choices数组中的索引。当输入参数 n 大于1时，需根据本参数进行不同响应对应的完整内容的拼接。

createdinteger

本次请求被创建时的时间戳。每个chunk有相同的时间戳。

modelstring

本次请求使用的模型。

objectstring

始终为chat.completion.chunk。

service_tierstring

该参数当前固定为null。

system_fingerprintstring

该参数当前固定为null。

usageobject

本次请求消耗的Token。只在include_usage为true时，在最后一个chunk显示。

completion_tokensinteger

模型输出的 Token 数。

prompt_tokensinteger

输入 Token 数。

total_tokensinteger

总 Token 数，为prompt_tokens与completion_tokens的总和。

Chat completions (OpenAI-compatible)

curl -X POST https://maas-api.hivoice.cn/v1/chat/completions \
 -H "Authorization: Bearer $UNISOUND_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
     "model": "u2-preview",
     "messages": [
         {"role": "user", "content": "你是谁？"}
     ]
 }'

200

{
  "id": "chatcmpl-cde4a60f-7458-48f8-93a4-5932bbd4b505",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "你好！我是U2，一个由云知声（Unisound）开发的AI助手。我可以帮助你回答问题、提供信息、进行对话等。有什么我可以帮助你的吗？",
        "role": "assistant",
        "reasoning_content": "用户用中文问"你是谁？"，意思是"你是谁？"或"Who are you?"我应该用中文回答，介绍我自己。根据系统提示，我是U2，由云知声（Unisound）建造的AI助手。我应该简单明了地回答这个问题。"
      },
      "finish_reason": "stop"
    }
  ],
  "created": 1778813741,
  "model": "u2-preview",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 94,
    "total_tokens": 135
  }
}