API 参考 - Qwen Intelligence

接入前提

在 SDK 中心安装 SDK。
已开通 Mobile-Use Agent 服务，并准备已发布的 Mobile-Use Agent 实例 ID 及其访问密钥。
使用 SDK 完成 AccessKey 认证。实例访问密钥通过 X-QI-Agent-Api-Key 传入，不能替代 AccessKey 签名。
设置 Content-Type: application/json 和 Accept: text/event-stream，请求体中的 stream 必须为 true。

调用方式

项目	说明
HTTP Method	`POST`
Path	`/gui/v1/chat/completions`
协议	HTTPS、SSE
请求格式	`application/json`
响应格式	`text/event-stream`
OpenAPI 认证	AccessKey 签名
RAM Action	`maasqiservice:GuiChatCompletionStream`

请求参数

参数	类型	必填	示例	说明
`X-QI-Agent-Api-Key`	string	是	`qis_xxx`	Agent 实例访问密钥，必须与实例 ID 对应。
`X-QI-Instance-Id`	string	是	`GUI_xxx`	已发布的 Mobile-Use Agent 实例 ID。
`X-QI-Session-Id`	string	否	`session-xxx`	首轮可省略，由服务端生成；后续步骤必须传回 SSE 正文中的 `qi_session_id`。
`Content-Type`	string	是	`application/json`	请求体媒体类型。
`Accept`	string	是	`text/event-stream`	接收 SSE 流式响应。

Body 参数

以下为 HTTP JSON 请求体字段。Chat Completions 字段使用 snake_case，例如 stream_options、include_usage、chat_template_kwargs 和 image_url。

参数	类型	必填	示例	说明
`model`	string	否	`""`	OpenAI 客户端兼容占位。模型由实例的已发布配置决定，该字段不能切换模型。
`messages`	array	是	-	当前步骤消息。首轮只能包含一条 `user`；续轮只能是一条 `tool` 后跟一条 `user`，不能携带完整历史。
`metadata`	object	否	-	当前步骤的设备、应用和兼容上下文。
`stream`	boolean	是	`true`	是否使用 SSE 流式响应。本接口必须传 `true`。
`stream_options`	object	否	`{"include_usage":true}`	OpenAI 兼容流式选项。
`chat_template_kwargs`	object	否	`{"enable_thinking":false}`	合并到模型模板参数并覆盖同名默认值。
`temperature`	number	否	`0.2`	采样温度，覆盖实例模型默认值。
`top_p`	number	否	`0.9`	Top-P 核采样参数。
`top_k`	integer	否	`20`	vLLM Top-K 采样参数。
`min_p`	number	否	`0.05`	vLLM Min-P 采样参数。
`min_tokens`	integer	否	`1`	最少生成 Token 数。
`max_completion_tokens`	integer	否	`2048`	OpenAI 兼容最大补全 Token 数，提供时必须大于 0。
`max_tokens`	integer	否	`2048`	OpenAI 兼容最大生成 Token 数，提供时必须大于 0。
`frequency_penalty`	number	否	`0.0`	频率惩罚参数，透传给主模型。
`presence_penalty`	number	否	`0.0`	存在惩罚参数，透传给主模型。
`repetition_penalty`	number	否	`1.1`	vLLM 重复惩罚参数。
`seed`	integer	否	`42`	随机种子。
`stop`	string 或 string[]	否	`["DONE"]`	停止序列。参数表建模为字符串数组。
`stop_token_ids`	integer[]	否	`[1,2]`	vLLM 停止 Token ID 列表。
`allowed_token_ids`	integer[]	否	`[10,11]`	允许生成的 Token ID 白名单。
`bad_words`	string[]	否	`["blocked"]`	禁止生成的词或字符串列表。
`ignore_eos`	boolean	否	`false`	是否忽略 EOS 并继续生成。
`skip_special_tokens`	boolean	否	`true`	是否跳过特殊 Token。
`include_reasoning`	boolean	否	`true`	是否请求上游生成推理字段；对客响应不会直接暴露内部思考。
`reasoning_effort`	string	否	`medium`	OpenAI 兼容推理强度，例如 `low`、`medium`、`high`。
`logprobs`	boolean	否	`false`	模型兼容参数。当前响应不提供输出 Token 对数概率明细。
`top_logprobs`	integer	否	`3`	候选 Token 对数概率数量。当前响应不返回相关明细。
`prompt_logprobs`	integer	否	`2`	Prompt Token 对数概率数量。当前响应不返回相关明细。
`n`	integer	否	`1`	建议设为 `1`，当前响应不承诺返回多个候选动作。
`parallel_tool_calls`	boolean	否	`false`	模型兼容开关，不扩大接口可用的 Mobile-Use Agent 动作集合。
`response_format`	object	否	`{"type":"json_object"}`	结构化输出选项，不能改变最终的 Mobile-Use Agent 工具调用结构。
`structured_outputs`	object	否	`{"choice":["tap","type"]}`	vLLM 结构化输出约束。
`mm_processor_kwargs`	object	否	`{"max_dynamic_patch":8}`	多模态预处理参数，按键透传给主模型。

扩展参数是否支持、允许范围和效果取决于实例所选模型。不支持的参数可能被模型拒绝。

`messages` 参数

每轮最后一条消息必须为 user。首轮和续轮均只提交当前步骤，不重放由服务端维护的历史消息。

参数	类型	必填条件	说明
`messages[].role`	string	是	`user` 或 `tool`。存在上一动作执行回执时，前一条必须为 `tool`。
`messages[].content`	array、string 或 object	是	`user` 使用内容数组；`tool` 填上一动作的真实执行结果。
`messages[].tool_call_id`	string	`role=tool` 时必填	引用上一轮响应中的 Tool Call ID。

user 消息的内容数组支持以下字段：

参数	类型	说明
`type`	string	文本使用 `text` 或 `input_text`；截图使用 `image_url` 或 `input_image`。
`text`	string	当前操作目标或页面状态补充。
`image_url`	string 或 object	截图引用；对象形式包含 `url`。
`image_url.url`	string	公开可访问的 HTTPS 图片 URL，或完整 Base64 图片 Data URL。
`image_data`	string	`input_image` 的兼容内联图片字段，可传 Base64 图片 Data URL。

每轮 user 消息必须包含恰好一张当前截图。已过期或无法访问的图片地址会被拒绝。

`metadata` 参数

参数	类型	说明
`screen_width`	integer	屏幕宽度正整数。使用 URL 截图时建议提供。
`screen_height`	integer	屏幕高度正整数。使用 URL 截图时建议提供。
`available_apps`	string[]	标准版的应用名称补充列表；新列表替换之前的补充项，但默认应用仍保留。专属版不使用此列表。
`app_list`	string[]	`available_apps` 的兼容别名。
`harness_message`	string	旧客户端动作回执；不能与前置 `tool` 消息同时传。新客户端优先使用 `tool` 消息。

Base64 图片可以从图片本身读取尺寸。tools 应省略或传空数组。

其他嵌套参数

参数	类型	说明
`chat_template_kwargs.enable_thinking`	boolean	覆盖主模型默认思考开关；开启后也不会返回 `reasoning_content`。
`chat_template_kwargs.preserve_thinking`	boolean	续轮中是否保留已有思考上下文。
`stream_options.include_usage`	boolean	是否在 `data:[DONE]` 前输出独立的 `usage` 统计块。
`response_format.type`	string	例如 `text`、`json_object` 或 `json_schema`。
`structured_outputs.choice`	string[]	允许的枚举文本集合。
`mm_processor_kwargs.max_dynamic_patch`	integer	视觉模型允许的最大动态图像 patch 数。

请求示例

首轮请求体

以下 1×1 PNG 仅用于接口连通性验证。真实调用必须替换为设备当前截图及实际宽高，不能据此认为设备动作已经执行。

{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "观察当前屏幕并返回下一步操作"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
          }
        }
      ]
    }
  ],
  "metadata": {
    "screen_width": 1,
    "screen_height": 1,
    "available_apps": [
      "设置",
      "浏览器"
    ]
  },
  "tools": [],
  "chat_template_kwargs": {
    "enable_thinking": false
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.2,
  "max_completion_tokens": 2048
}

续轮 `messages`

合并 SSE 中的 tool_calls 并完整解析 function.arguments 后，由调用方执行动作。动作确实执行成功后，使用上一轮 Tool Call ID、真实执行结果和最新截图继续调用。收到结束或用户接管动作时，停止自动执行或转交用户。动作建议本身不代表设备动作已经执行成功。

[
  {
    "role": "tool",
    "tool_call_id": "call_gui_1",
    "content": "点击已完成"
  },
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "这是操作后的屏幕，请继续"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/screenshot-next.png"
        }
      }
    ]
  }
]

会话管理

首轮可省略 X-QI-Session-Id。
从 SSE 正文保存 qi_session_id。
后续步骤通过 X-QI-Session-Id 传回同一值。
同一会话顺序调用，不并发提交多个步骤；不同任务使用不同会话。
不依赖网关透传的自定义响应头，实际标识以 SSE 正文为准。

SSE 响应

响应 Content-Type 为 text/event-stream。事件以空行分隔，解析 data: 后的 JSON，并忽略冒号开头的心跳注释。一次网络读取不一定包含完整事件，需要先缓存并拼接后再解析。

数据字段

字段	说明
`id`	响应标识。
`created`	响应创建时间，Unix 秒。
`object`	`chat.completion.chunk`。
`model`	空字符串。
`qi_session_id`	会话 ID，保存后用于后续调用。
`qi_request_id`	Agent 请求 ID，用于问题排查。
`choices[0].delta.content`	正文增量，按顺序拼接。
`choices[0].delta.tool_calls`	动作工具调用增量，按 `index` 拼接。
`choices[0].delta.tool_calls[].index`	合并同一个动作调用的索引。
`choices[0].delta.tool_calls[].function.arguments`	JSON 字符串分片，必须拼接完整并解析后再执行。
`choices[0].finish_reason`	内容结束原因，常见值为 `stop`、`tool_calls`、`length`。之后仍可能返回用量事件。
`qi_event`	进度或错误事件，不拼入正文。
`usage`	`include_usage=true` 时独立返回的用量块，此时 `choices` 为空数组。
`usage.prompt_tokens`	输入 Token 数。
`usage.completion_tokens`	输出 Token 数。
`usage.total_tokens`	Token 总数。Token 用量不是最终账单。

事件通常按角色事件、内容或进度、finish_reason、可选 usage、data:[DONE] 的顺序返回，但事件数量和分片边界不固定。

progress 事件可以展示 message，不要写死阶段数量。
error 事件表示执行失败，即使 HTTP 状态为 200。读取 code、http_status、message、retryable；部分错误还包含 param、reason。
[DONE] 仅表示流结束，不单独代表成功。连接断开且没有结束标记时，结果可能不完整。

流内错误示例

data:{"qi_event":{"type":"error","stage":"input_validation","code":"invalid_parameter","http_status":400,"message":"The reference image URL has expired. Upload the image again or provide a new signed URL.","retryable":false,"reason":"image_url_expired"}}

data:[DONE]

返回参数

普通响应模型声明以下网关字段；Mobile-Use Agent 的业务结果通过 SSE 正文返回。

参数	类型	说明
`requestId`	string	POP 网关生成的请求标识，用于网关链路追踪。Agent 请求 ID 以 SSE 正文中的 `qi_request_id` 为准。

错误码

HTTP 状态码	错误码	错误信息	说明
`400`	`ContentFilter`	`Your request was blocked by the content filter.`	请求被内容安全策略拦截。
`400`	`InvalidParameter`	`The specified request parameter is invalid.`	指定的请求参数无效。
`401`	`InvalidApiKey`	`The specified API key is invalid.`	指定的 API Key 无效。
`403`	`ServiceNotActivated`	`The required Agent service is not activated for this account.`	当前账号未开通所请求的 Agent 服务，无法调用该接口。
`404`	`InvalidAgentNotFound`	`The published Agent is not found.`	未找到已发布的 Agent。
`409`	`IdempotencyConflict`	`The request ID was reused with different request parameters.`	请求 ID 被用于不同的请求参数。
`409`	`SessionConflict`	`The session state conflicts with the request.`	Session 状态与请求冲突。
`413`	`RequestEntityTooLarge`	`The request body is too large.`	请求体过大。
`429`	`QuotaExhausted`	`The Agent trial quota has been exhausted.`	Agent 试用额度已耗尽。
`500`	`InternalError`	`An internal server error occurred.`	发生内部服务器错误。
`502`	`UpstreamServiceError`	`The upstream Agent runtime failed to complete the request.`	上游 Agent Runtime 未能完成请求。
`503`	`ServiceUnavailable`	`The service is temporarily unavailable.`	服务暂时不可用。

排查与重试

未建立 SSE 时，按 HTTP 状态和错误码处理。AccessKey 签名认证与实例访问密钥校验是不同的认证环节。
参数错误、服务未开通、额度不足或会话冲突时，先修正条件再调用。图片过期或无权限时，更换有效链接。
流内错误根据 qi_event.retryable 判断是否退避重试，不要把 HTTP 200 或 [DONE] 单独视为成功。
反馈问题时提供时间、接口名、qi_request_id 和网关 RequestId，不要提供密钥、完整签名链接或敏感输入。

​接入前提

​调用方式

​请求参数

​Header 参数

​Body 参数

​messages 参数

​metadata 参数

​其他嵌套参数

​请求示例

​首轮请求体

​续轮 messages

​会话管理

​SSE 响应

​数据字段

​流内错误示例

​返回参数

​错误码

​排查与重试