MaaS 产品文档
POST
OpenAI_Chat
https://maas-api.cn-huabei-1.xf-yun.com/v2
API Key：点击 API调用 / APIKEY管理 界面获取，示例：ak-f30b1********fc84b82e86a
Model ID：点击 API调用 获取，示例：xop3qwen32bvl

1 请求参数 ​

model
string必填
指定要调用的模型ID。请参考 服务管控 > 模型服务列表 获取。
messages
array必填
可选值：[{"role": "user", "content": [...]}]
表示对话上下文的消息列表。其中，role 用于标识消息发送方, content 则为包含文本和图像信息的数组。
role
string
可选值：user
user表示用户的问题
content
array
可选值：--
包含文本和图像信息的数组
type: text
string
用户的文本输入
image_url
object
图像数据, 包含一个 url 字段
url
string
图像的URL或者Base64编码的图像数据
stream
boolean可选
可选值：true 或 false，默认值为 false
指定是否采用流式响应模式。若设置为 true，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应
temperature
float可选
可选值：取值为[0,1],默认值为0.7
核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高
max_tokens
int可选
可选值：取值为[1,8192]，默认值为2048
限制生成回复的最大 token 数量

示例：

json
[{"role": "user","content": [{"type": "text","text": "这题的答案是什么"},{"type": "image_url","image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."}}]}]

2 请求示例 ​

如果想使用 HTTP 请求的流式输出，请参考如下实例：

python
from openai import OpenAI
api_key = "<从服务管控页面获取 对应服务的APIKey>"  请替换为您的 API Key
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"
client = OpenAI(api_key=api_key,base_url=api_base)

try:
    response = client.chat.completions.create(
        model="<从服务管控页面获取 对应服务的ModelID>",  请根据实际情况替换为您的 Model ID
        messages=[{"role": "user","content": [{"type": "text","text": "这题的答案是什么"},{"type": "image_url","image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."}}]}],
        stream=True,
        temperature=0.7,
        max_tokens=8192)
    full_response = ""for chunk in response:if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.contentprint(content, end="", flush=True)  实时打印每个片段
            full_response += content
    print("\n\n ------完整响应：", full_response)
except Exception as e:print(f"Error: {e}")

3 响应 ​

  1. 成功响应示例

  • 流式响应会返回一系列的事件（data-only server-sent events），每个事件都是一个JSON对象，称为数据块（chunk）。

  • 下面是几个响应数据块的示例：

（1）数据块 1 (包含内容)

json
{"id": "cht000b920a@dx194e0205ccbb8f3700","object": "chat.completion.chunk","created": 1738927005,"model": "xqwen2d5s32bvl","choices": [{"index": 0,"delta": {"role": "assistant","content": "这张图"},"finish_reason": null}]}

（2）数据块 2 (继续包含内容)

json
{"id": "cht000b920a@dx194e0205ccbb8f3700","object": "chat.completion.chunk","created": 1738927005,"model": "xqwen2d5s32bvl","choices": [{"index": 0,"delta": {"content": "标显示的是..."},"finish_reason": null}]}

（3）结束数据块 (finish_reason 为 stop)

json
{"id": "cht000b920a@dx194e0205ccbb8f3700","object": "chat.completion.chunk","created": 1738927005,"model": "xqwen2d5s32bvl","choices": [{"index": 0,"delta": {},"finish_reason": "stop"}],"usage": {"prompt_tokens": 44,"completion_tokens": 42,"total_tokens": 86}}
  1. 异常结果示例
http
Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型：xqwen2d5s32bvl (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}
  1. 响应数据参数

在流式响应中，每个数据块（chunk）都包含以下字段：

id
string
唯一标识符，标识本次对话调用的唯一ID。
object
string
对象类型，对于流式响应，其值为 chat.completion.chunk。
created
int
响应生成时间的Unix时间戳（秒级）。
model
string
实际调用的模型名称。
choices
array
包含模型生成回复候选项的数组。
index
int
回复候选项在数组中的索引位置，从0开始。
delta
object
包含增量消息内容的对象。
role
string
在第一个数据块中出现，值为 assistant。
content
string
模型生成的增量回复文本内容。
finish_reason
string
在最后一个数据块中出现，指示回复生成结束的原因，如 "stop"。
usage
object
在最后一个数据块中出现（需在请求中加入stream_options={"include_usage": True}），包含token使用统计信息。
completion_tokens
int
回复文本消耗的token数量。
prompt_tokens
int
输入prompt消耗的token数量。
total_tokens
int
prompt与回复消耗token数量的总和。