API 参考

接入前提

在 SDK 中心安装 SDK。
已开通 CUA Agent 服务，准备已发布的 CUA 实例 ID 及其访问密钥。
CUA 仅提供标准版。
使用阿里云 SDK 或 OpenAPI 签名完成 AccessKey 认证；实例访问密钥另放在 X-QI-Agent-Api-Key，不能替代 AccessKey 签名。
设置 Content-Type: application/json、Accept: text/event-stream，stream 必须为 true。

调用方式

方法与路径：POST /cua/v1/chat/completions；
X-QI-Instance-Id 指定实例，按已发布的 CUA 标准版配置执行；请求体 model 是兼容占位，不能切换模型。
响应为 SSE 事件，不是一个完整 JSON；持续读取到流结束，并检查流内错误。当前 CUA 在单步模型决策完成后返回动作，不是逐 Token 输出。

会话管理

首轮可省略 X-QI-Session-Id，从 SSE 正文保存 qi_session_id，后续通过同名请求头续接。同一会话顺序调用；不同会话使用不同标识。不要依赖网关透传自定义响应头，实际标识以 SSE 正文为准。X-QI-Request-Id 可省略，由服务端生成；同一步重试保持 ID 和输入不变，新一步使用新 ID。

基本信息

项目	值
请求路径	`/cua/v1/chat/completions`
请求方法	POST
协议	HTTPS、SSE
认证方式	AK
Content-Type	`application/json`
Accept	`text/event-stream`
返回类型	synchronous

参数	类型	必填	示例	说明
X-QI-Agent-Api-Key	string	是	`qis_<instance_api_key>`	CUA 实例访问密钥。POP AK 签名与实例密钥各自校验；此 Header 可传原始 qis_ 密钥或 Bearer 密钥。
X-QI-Instance-Id	string	是	`CUA_<instance_id>`	目标已发布 CUA 标准版实例 ID，须与实例密钥对应。
X-QI-Session-Id	string	否	`session-cua-1`	首轮可省略或置空，由服务端生成；续轮复用返回的 qi_session_id，不重新发送完整历史。

Body 参数

CUA 当前一步输入：首轮为任务文本和一张截图；续轮为上一动作的 tool 回执和一张新截图，不接受完整历史。

参数	类型	必填	枚举	示例	说明
messages	array	是			必填；首轮仅一条 user，续轮仅一条 tool 后接一条 user。每步恰好一张截图，首轮还需非空任务文本。
model	string	否		`" "`	兼容字段，可省略或传空字符串；实际模型由实例或调试配置的模型目录决定，不按此字段路由。
stream	boolean	是	`true`	`true`	本 SSE API 请固定传 true。当前 CUA 完成单步模型决策后输出结果，不是逐 Token 实时输出。
stream_options	object	否			SSE 可选设置。
tools	array	否		`[]`	只能省略或传空数组；CUA 使用固定 computer_use 工具，不允许自定义工具。
metadata	object	否			截图辅助信息；不接收 GUI 应用列表或 AIGC 生图参数作为 CUA 运行配置。

嵌套参数

参数	类型	必填	枚举	示例	说明
messages[]	object	是			当前步骤消息；不支持 system、assistant 或整段历史消息。
messages[].content	array	是			user 使用多模态数组。tool 可用 text 内容项数组回传执行结果；后端另兼容非空字符串或对象。
messages[].content[]	object	是			文本或截图项。文本填 text；图片填 image_url.url 或 image_data。
messages[].content[].image_data	string	否		`data:image/png;base64,<IMAGE_BASE64>`	input_image 的兼容内联截图字段，使用完整 Base64 图片 Data URL，不接受无前缀原始 Base64。
messages[].content[].image_url	object	否			截图引用；推荐 url 对象形式，后端也兼容 image_url 字符串。
messages[].content[].image_url.url	string	是		`https://example.com/desktop.png`	可访问的截图 HTTP(S) URL 或完整 data:image/...;base64,...。推荐 HTTPS；签名链接须未过期。
messages[].content[].text	string	否		`打开浏览器并访问指定页面。`	文本内容。首轮 user 必须提供任务目标；tool 填真实执行结果。
messages[].content[].type	string	是	`text`、`input_text`、`image_url`、`input_image`	`image_url`	文本为 text/input_text；截图为 image_url/input_image。
messages[].role	string	是	`user`、`tool`	`user`	user 或 tool。首轮为 user；续轮顺序为 tool、user。
messages[].tool_call_id	string	否		`call_cua_1`	role=tool 时必填，必须等于同一 Session 上一步返回的 computer_use 调用 ID。
metadata.screen_height	integer	否		`1080`	截图高度，提供时为正整数；内联图片实际尺寸优先，不覆盖执行桌面 screenHeight。
metadata.screen_width	integer	否		`1920`	截图宽度，提供时为正整数；内联图片实际尺寸优先，不覆盖执行桌面 screenWidth。
stream_options.include_usage	boolean	否		`true`	为 true 时，在结束标记前返回独立 usage 事件，choices 为空数组。

tools[]：工具数组的兼容占位元素。CUA 不接受自定义工具，tools 应省略或传空数组，不应填写工具条目。

请求参数补充说明

JSON 字段写法

以下示例为 HTTP JSON 请求体。Chat Completions 字段使用 snake_case，例如 stream_options、include_usage、image_url、tool_call_id；参数表的设计名称可能显示为驼峰，请按示例中的 JSON 键发送。

请求示例

以下为请求体结构示例。实例 ID 和实例访问密钥通过请求头传入。请将截图地址替换为设备当前真实截图，并填写实际宽高；示例地址不可直接用于运行，尚不代表已完成网关实测。

{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "观察桌面，打开浏览器并找到设置页面"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/desktop.png"
          }
        }
      ]
    }
  ],
  "tools": [],
  "metadata": {
    "screen_width": 1920,
    "screen_height": 1080
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

截图与动作回执

首轮只传一条 user，包含非空任务目标和恰好一张当前截图。图片使用可访问的 HTTPS URL 或完整 Base64 图片 Data URL；签名链接在调用期间必须有效。
收到 computer_use 工具调用后，完整解析 function.arguments，再由调用方执行动作。动作建议本身不代表设备已执行成功。
续轮使用返回的会话 ID，messages 仅传 [tool,user]，不要重放历史 assistant 消息。tool_call_id 使用上一轮返回的 ID，content 填真实执行结果；user 带最新截图。
收到 finished 动作时停止续接；收到 ask_user 时向用户提问，再回传实际回答。涉及付款、删除或授权等敏感操作，应由调用方增加授权和确认环节。

续轮 messages 格式（动作确实执行成功后才能填写成功回执）：

[
  {
    "role": "tool",
    "tool_call_id": "call_cua_1",
    "content": [
      {
        "type": "text",
        "text": "点击已实际执行，页面已更新"
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/desktop-next.png"
        }
      }
    ]
  }
]

请替换截图地址、tool_call_id 和实际执行结果。tool.content 除上述文本数组外，也兼容非空字符串或对象；回传终端结果时对象可包含 bash_returncode、bash_output、bash_error，用户回答可使用 user_response。

设备元数据

metadata.screen_width、screen_height 为截图像素宽高，提供时必须为正整数；内联图片优先读取图片自身尺寸。
执行桌面的 screenWidth、screenHeight 来自 CUA 实例，用于动作坐标投影，不由 metadata 的截图尺寸覆盖。
tools 应省略或为空数组。CUA 使用固定 computer_use 工具。

模型与运行配置

CUA 的模型、提示组件、桌面坐标、截图预处理、思考及重试设置来自实例配置。

200 返回参数

SSE 流式响应元数据。业务数据按 chat.completion.chunk 事件返回，最终以 data:[DONE] 结束；完整字段说明见返回参数补充说明。

字段	类型	示例	说明
requestId	string	`request-20260918-001`	POP 网关请求标识，用于网关链路追踪；Agent 请求标识以 SSE 正文中的 qi_request_id 为准，不应从 data.requestId 读取。

返回参数补充说明

SSE 读取规则

响应 Content-Type 为 text/event-stream。以空行分隔事件，解析 data: 后的 JSON；忽略冒号开头的心跳注释。一次网络读取不一定是一个完整事件，需缓存并拼接后解析。当前 CUA 完成单步模型决策后输出动作结果，不是逐 Token 的模型透传。

数据字段

字段	使用方式
id / created	响应标识与创建时间（Unix 秒）。
object / model	object 为 chat.completion.chunk；model 为兼容字段，不用于选择模型。
qi_session_id / qi_request_id	保存会话与请求标识，用于续接及排查；不同于 POP 网关 RequestId。
choices[0].delta.role	初始事件中的 assistant 角色。
choices[0].delta.reasoning_content	模型提供时返回的推理文本，与动作参数分开处理。
choices[0].delta.tool_calls	本步 computer_use 工具调用，包含 id、type 和 function；function.arguments 是 JSON 字符串，完整解析后由调用方执行。CUA 返回完整动作，不依赖条目上的 index 字段。
choices[0].finish_reason	非空表示本步结果结束，动作结果通常为 tool_calls；不等于整个任务完成。
qi_event	流内错误信息，不拼入正文。
usage	include_usage=true 时独立返回，choices 为空数组；prompt_tokens、completion_tokens、total_tokens 是 Token 用量，不是最终账单。

动作调用

工具名称固定为 computer_use。对 function.arguments 再做一次 JSON 解析，然后按 action_type 分发：

action_type	使用方式
pyautogui_code	在受控桌面环境执行 code。
execute_bash	在受控终端执行 command。
wait	等待界面变化，再提交新截图。
ask_user	展示 question，回传用户真实回答。
action_sequence	按顺序处理 actions 中的子动作。
finished	status 为 success 或 failure，可附带 answer；表示任务结束。

动作结构示例（仅展示一条 tool_call，不表示应直接执行此示例）：

{"id":"call_cua_1","type":"function","function":{"name":"computer_use","arguments":"{\"action_type\":\"wait\"}"}}

完成与异常

通常按角色、动作结果、finish_reason、可选 usage、data:[DONE] 的顺序返回。事件数量及分片边界不固定。

error 表示执行失败，即使 HTTP 为 200。读取 code、http_status、message、retryable，部分错误还包含 param、reason。
[DONE] 仅代表流结束，不单独代表成功；断开且无结束标记时，结果可能不完整。
动作是否执行成功由调用方的真实回执确定，不要在断连后无条件重复执行已完成的动作。

流内错误示例（只展示相关字段）：

data:{"qi_event":{"type":"error","stage":"execution","code":"upstream_error","http_status":502,"message":"The upstream Agent runtime failed to complete the request.","retryable":true}}

data:[DONE]

HTTP/网关错误参见错误码表；流已建立后的错误按 qi_event 处理。

补充信息

排查与重试

未建立 SSE 时按 HTTP 状态和错误码表处理；POP AccessKey 签名与 QICloud 业务认证不是同一层校验。
参数错误、服务未开通、额度不足、会话冲突，先修正条件再调用。图片过期或无权限时更换有效链接。
流内错误按 qi_event.retryable 判断是否退避重试；不要把 HTTP 200 或 [DONE] 单独当作成功。重试前确认动作是否已执行，避免重复副作用。
反馈问题时提供时间、接口名、qi_request_id 和网关 RequestId，不要提供密钥、签名、完整签名链接或敏感截图。

返回示例

{
  "requestId": "request-20260918-001"
}

错误码

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.	服务暂时不可用。

变更历史

日期	API 版本	变更内容
2026-10-27	2026-10-27	首次发布流式调用文档。

​接入前提

​调用方式

​会话管理

​基本信息

​Header 参数

​Body 参数

​嵌套参数

​请求参数补充说明

​JSON 字段写法

​请求示例

​截图与动作回执

​设备元数据

​模型与运行配置

​200 返回参数

​返回参数补充说明

​SSE 读取规则

​数据字段

​动作调用

​完成与异常

​补充信息

​排查与重试

​返回示例

​错误码

​变更历史