Skip to main content
Qwen Intelligence home page
Mobile Planner Agent 规划智能体

API参考

接入前提

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

调用方式

  • 方法与路径：POST /pa/v1/chat/completions。
  • X-QI-Instance-Id 指定实例，按已发布配置执行；请求体 model 是兼容占位，不能切换模型。
  • 响应为 SSE 增量事件，不是一个完整 JSON；持续读取到流结束，并检查流内错误。

会话管理

首轮可省略 X-QI-Session-Id，从 SSE 正文保存 qi_session_id，后续通过同名请求头续接。同一会话顺序调用；不同会话使用不同标识。不要依赖网关透传自定义响应头，实际标识以 SSE 正文为准。

流控信息

当前云产品API请求速率暂未透出。

授权信息

如下是此API对应的授权信息，用于RAM权限策略语句的Action元素中，为RAM用户或RAM角色授予调用此API的权限。请通过RAM 访问控制设置，使用方法可参考访问控制帮助文档。 具体说明如下：
  • 操作：是指具体的权限点。
  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：
    • 对于必选的资源类型，用前面加 * 表示。
    • 对于不支持资源级授权的操作，用全部资源表示。
  • 条件关键字：是指云产品自身定义的条件关键字。
  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
操作访问级别资源类型条件关键字关联操作
maasqiservice:PaChatCompletionStreamNone全部资源
*		无无

请求语法

POST /pa/v1/chat/completions HTTP/1.1

请求参数

字段路径类型必填字段详情
X-QI-Agent-Api-Keystring是Agent 实例访问密钥，用于 QICloud Customer 接口鉴权。
示例值:qis_xxx
X-QI-Instance-Idstring是已发布的 PA 实例 ID，必须与 X-QI-Agent-Api-Key 对应，且实例类型为 PA。
示例值:PA_xxx
X-QI-Session-Idstring否可选会话标识。首轮可省略，由服务端生成；后续轮次传回以续接 PA Session。
示例值:session-xxx
bodyobject否PA 调用请求体。使用 OpenAI-Compatible Chat Completions 的 JSON 字段格式；messages 必填，stream 设为 true。模型由实例配置决定。
body.chatTemplateKwargsobject否vLLM/OpenAI-Compatible 模板参数对象。请求值与模型默认值合并，请求同名键优先，并原样传给模型。
body.chatTemplateKwargs.enableThinkingboolean否通过 chat_template_kwargs 控制模型是否生成 reasoning_content；该值会传给 PA 模型。
示例值:true
body.chatTemplateKwargs.preserveThinkingboolean否是否让模型在续轮中保留并复用已有思考内容；按 vLLM/Qwen chat_template_kwargs 原样透传。
示例值:true
body.maxCompletionTokensinteger<int64>否最大补全 Token 数，提供时必须大于 0，并作为 OpenAI 兼容模型参数传入。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:2048
body.messagesarray<object>是对话消息列表。首次调用可提交一轮或已有多轮对话；携带已有会话 ID 续接时，保留完整且未改动的历史消息前缀，并追加本轮消息。工具结果通过 role=tool 和对应的 tool_call_id 关联。
body.messages[]object否单条 Chat Completions 消息。对话使用 user、assistant、tool；本轮可选文本指令使用 system 或 developer。assistant 工具调用与 tool 结果通过 tool_call_id 关联。
body.messages[].contentarray<object>否消息内容。PA 支持文本及多模态内容；图片 URL 或 base64 Data URL 会通传到支持多模态的 PA 模型。
示例值:请分析图片内容
body.messages[].content[]object否user 多模态内容分片；纯文本请求也可以直接把 content 设为字符串。
body.messages[].content[].typestring否内容分片类型。PA user 消息支持 text 或 image_url。
示例值:text
body.messages[].content[].textstring否type=text 时的非空文本。
示例值:请分析这张图片
body.messages[].content[].imageUrlobject否type=image_url 时的图片引用；支持 HTTPS URL 或 data:image/...;base64,...。
body.messages[].content[].imageUrl.urlstring否图片地址。远程图片必须使用 HTTPS；也可传 Base64 Data URL。
示例值:https://example.com/image.png
body.messages[].rolestring否消息角色：user、assistant、tool、system 或 developer。system/developer 用于本轮可选文本指令覆盖；省略时使用实例配置中的指令。工具结果使用 tool 并关联 tool_call_id。
示例值:user
body.messages[].toolCallIdstring否role=tool 时必填，必须匹配此前 assistant.tool_calls 中的 id。
示例值:call_weather_1
body.messages[].toolCallsarray<object>否role=assistant 时可携带的函数调用列表；用于多轮工具调用续接。
body.messages[].toolCalls[]object否assistant 历史消息中的一项结构化工具调用，保留服务端返回的 id、type 和 function。
body.messages[].toolCalls[].idstring否工具调用 ID；后续 tool 消息通过 tool_call_id 引用。
示例值:call_weather_1
body.messages[].toolCalls[].typestring否工具调用类型，当前固定为 function。
示例值:function
body.messages[].toolCalls[].functionobject否历史工具调用的函数信息，包含 name 及 JSON 字符串形式的 arguments；续轮应保留实际返回值。
body.messages[].toolCalls[].function.namestring否要调用的函数名。
示例值:get_weather
body.messages[].toolCalls[].function.argumentsstring否函数参数的 JSON 对象字符串。
示例值: {"city":"杭州"}
body.modelstring否为 OpenAI 客户端兼容保留；路由时忽略，实际模型由实例已发布配置决定，响应 model 固定为空字符串。
示例值:" "
body.streamboolean是是否使用 SSE 流式响应。本接口必须传 true。
示例值:true
body.streamOptionsobject否OpenAI 兼容流式选项。
body.streamOptions.includeUsageboolean否是否在 data:[DONE] 之前输出 usage 统计块。
示例值:true
body.temperaturenumber<double>否采样温度；作为 OpenAI 兼容模型参数传入，覆盖模型默认值。
示例值:0.2
body.toolsarray<object>否本次请求可用的函数工具定义数组。PA 会将每个命名函数注册到运行时 Toolkit，并流式返回 tool_calls。
body.tools[]object否单个工具定义，当前仅支持 type=function 且 function.name 非空。
body.tools[].functionobject否函数工具定义，包含名称、描述与 JSON Schema 参数。
body.tools[].function.descriptionstring否函数用途说明，供模型判断何时调用该工具。
示例值:查询指定城市天气
body.tools[].function.namestring否函数名，必须非空；用于匹配 assistant.tool_calls 与后续 tool 结果。
示例值:get_weather
body.tools[].function.parametersobject否函数参数 JSON Schema，按原始 JSON 传给模型；未提供时使用空对象 Schema。
body.tools[].function.parameters.propertiesobject否JSON Schema 的属性定义。
body.tools[].function.parameters.properties.cityobject否示例业务参数 city 的 Schema。实际字段由调用方工具定义决定。
body.tools[].function.parameters.properties.city.descriptionstring否示例参数说明。
示例值:要查询天气的城市名称
body.tools[].function.parameters.properties.city.typestring否示例 city 字段的 JSON Schema 类型。
示例值:string
body.tools[].function.parameters.requiredarray<string>否JSON Schema 必填字段名称数组。
body.tools[].function.parameters.required[]string否必填字段名称示例。
示例值:city
body.tools[].function.parameters.typestring否函数 parameters 根 Schema 类型，通常为 object。
示例值:object
body.tools[].function.strictboolean否是否要求模型严格遵循函数参数 JSON Schema。
示例值:true
body.tools[].typestring否工具类型，当前必须为 function。
示例值:function
body.topPnumber<double>否Top-P 采样参数；作为 OpenAI 兼容模型参数传入，覆盖模型默认值。
示例值:0.9
body.maxTokensinteger<int64>否OpenAI 兼容最大生成 Token 数，提供时必须大于 0。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:2048
body.frequencyPenaltynumber<double>否频率惩罚参数，透传给 PA 模型。
示例值:0.0
body.presencePenaltynumber<double>否存在惩罚参数，透传给 PA 模型。
示例值:0.0
body.stoparray<string>否停止序列。兼容单个字符串或字符串数组；此处展示数组形式。
示例值:["END"]
body.stop[]string否一个停止字符串。模型是否接受及停止行为取决于模型。
示例值:end
body.seedinteger<int64>否随机种子。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:42
body.logprobsboolean否模型兼容参数，JSON 字段为 logprobs。是否接受及生效取决于实例所用模型；当前 Agent 响应不提供 Token 对数概率明细。
示例值:false
body.topLogprobsinteger<int64>否模型兼容参数，JSON 字段为 top_logprobs。用于支持该功能的模型；当前 Agent 响应不提供候选 Token 概率明细。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:3
body.responseFormatobject否结构化响应格式，例如 json_object 或 json_schema。
body.responseFormat.typestring否响应格式类型，例如 text、json_object 或 json_schema。
示例值:json_object
body.topKinteger<int64>否vLLM Top-K 采样参数。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:20
body.minPnumber<double>否vLLM Min-P 采样参数。
示例值:0.05
body.repetitionPenaltynumber<double>否vLLM 重复惩罚参数。
示例值:1.1
body.includeReasoningboolean否是否要求上游返回推理内容；具体能力取决于模型。
示例值:true
body.skipSpecialTokensboolean否是否跳过特殊 Token。
示例值:true
body.reasoningEffortstring否OpenAI 兼容推理强度，例如 low、medium、high。
示例值:high
body.parallelToolCallsboolean否是否允许模型并行生成多个工具调用。
示例值:false
body.toolChoicestring否工具选择策略，支持 auto、none、required 或模型支持的命名选择。
示例值:auto
body.ninteger<int64>否建议设为 1。该参数是否被模型接受取决于模型；当前 PA 响应不会透出多个候选结果，请勿按多候选返回使用。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:1
body.stopTokenIdsarray<integer<int64>>否vLLM 停止 Token ID 列表。
示例值:[1,2]
body.stopTokenIds[]integer<int64>否一个停止 Token 的整数 ID，需使用目标模型的词表 ID。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:1
body.ignoreEosboolean否是否忽略 EOS 并继续生成。
示例值:false
body.minTokensinteger<int64>否最少生成 Token 数。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:1
body.promptLogprobsinteger<int64>否模型兼容参数，JSON 字段为 prompt_logprobs。是否接受取决于模型；当前 Agent 响应不返回输入 Token 概率明细。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:2
body.allowedTokenIdsarray<integer<int64>>否允许生成的 Token ID 白名单。
示例值:[10,11]
body.allowedTokenIds[]integer<int64>否一个允许生成的 Token 整数 ID，需使用目标模型的词表 ID。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:1
body.badWordsarray<string>否禁止生成的词或字符串列表。
示例值:["blocked"]
body.badWords[]string否一个不希望模型生成的词或字符串。
示例值:word
body.structuredOutputsobject否vLLM 结构化输出约束。
body.structuredOutputs.choicearray<string>否允许的枚举文本集合。
示例值:["yes","no"]
body.structuredOutputs.choice[]string否一项允许模型选择的文本值。
示例值:text
body.mmProcessorKwargsobject否多模态预处理器参数，按键原样透传给 vLLM。
body.mmProcessorKwargs.maxDynamicPatchinteger<int64>否示例：视觉模型允许的最大动态图像 patch 数。
注意
该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。
示例值:8

请求说明

JSON 字段写法

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

请求示例

以下请求结构已使用 Python SDK 通过网关调用验证。实例 ID 与实例访问密钥通过请求头传入；输出文本由实际模型生成，不保证固定措辞。 
{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": "请简要说明杭州适合旅游的季节"
    }
  ],

  "tools": [],

  "temperature": 0.2,
  "max_completion_tokens": 2048,
  "chat_template_kwargs": {
    "enable_thinking": true
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

多轮对话与工具调用

  • 首轮可只发送 user，也可在未指定会话 ID 时传入已有 user/assistant/tool 对话。
  • 续接会话时，messages 保留此前完整对话（包括上次返回的 assistant 内容和 tool_calls），并在末尾追加新消息；不要修改、删减或重复已保存的历史前缀。
  • 如果收到工具调用，先按 index 拼接完整 function.arguments，再执行工具。下一轮加入 role=tool 的真实结果，tool_call_id 必须对应之前 assistant.tool_calls 的 id。
  • tools 使用 OpenAI function 结构，函数名在同一请求中唯一，parameters 使用 JSON Schema。下方 city 只是示例工具的参数名，不是所有 PA 请求的固定字段。
工具定义示例： 
{"tools":[{"type":"function","function":{"name":"get_weather","description":"查询指定城市的天气","parameters":{"type":"object","properties":{"city":{"type":"string","description":"城市名称"}},"required":["city"]}}}]}

图片与思考输出

多模态输入在 user.content 同时放 text 与 image_url 分片，例如： 
[{"type":"text","text":"描述这张图片"},{"type":"image_url","image_url":{"url":"https://example.com/image.png"}}]
替换为有效公开 HTTPS 图片地址或 Base64 图片 Data URL；图片 URL 在调用期间必须有效。模型是否支持图片取决于实例选择的模型。 启用思考使用 chat_template_kwargs.enable_thinking。若模型返回推理文本，增量放在 reasoning_content；正文放在 content。未显式设置时沿用模型默认值，因此可能仍有推理输出。二者需分开保存和展示，不要相互拼接。

可选指令覆盖

可在 messages 中传入文本形式的 system 或 developer 消息，作为本轮指令；省略时使用 Agent 配置中的指令。这些指令是请求级设置，后续仍需使用时应再次传入；会话续接时保持实际对话历史不变。它不代表调用方可以修改模型、工具权限或保证模型输出固定文本。

模型兼容参数

请求中显式提供的采样参数优先于模型默认值，chat_template_kwargs 按键合并。请用嵌套形式 "chat_template_kwargs":{"enable_thinking":true}，其中的键也保持 snake_case。扩展参数是否支持、允许范围和效果取决于实例所选模型；不支持的参数可能被模型拒绝。 Agent 不原样转发模型的完整响应：当前不返回 logprobs、top_logprobs 或 prompt_logprobs 明细；n 建议保持 1，不承诺返回多候选结果。

返回参数

字段路径类型必填字段详情
requestIdstring—Id of the request 由 POP 网关生成的请求标识，用于网关链路追踪；Agent 执行请求 ID 以 SSE 正文中的 qi_request_id 为准。
示例值:request-20260904-001

返回说明

SSE 读取规则

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

数据字段

字段使用方式
id / created响应标识与创建时间（Unix 秒）。
object / modelobject 为 chat.completion.chunk；model 为空字符串。
qi_session_id / qi_request_id保存会话与请求标识，用于续接及排查。
choices[0].delta.content按顺序拼接的正文增量。
choices[0].delta.reasoning_content模型提供时返回的推理文本增量，与 content 分开处理。
choices[0].delta.tool_calls按 index 拼接 id、function.name 和 function.arguments；arguments 完整后再解析 JSON、执行工具。
choices[0].finish_reason非空表示内容结束，常见 stop、tool_calls、length；之后仍可能返回用量事件。
qi_event进度或错误信息，不拼入正文。
usageinclude_usage=true 时独立返回，choices 为空数组；prompt_tokens、completion_tokens、total_tokens 是 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]
HTTP/网关错误参见错误码表；流已建立后的错误按 qi_event 处理。

返回示例

json 格式 
{
  "requestId": "request-20260904-001"
}

错误码

HTTP 状态码错误码错误信息操作
400ContentFilterYour request was blocked by the content filter.诊断
400InvalidParameterThe specified request parameter is invalid.诊断
401InvalidApiKeyThe specified API key is invalid.诊断
403ServiceNotActivatedThe required Agent service is not activated for this account.诊断
404InvalidAgentNotFoundThe published Agent is not found.诊断
409IdempotencyConflictThe request ID was reused with different request parameters.诊断
409SessionConflictThe session state conflicts with the request.诊断
413RequestEntityTooLargeThe request body is too large.诊断
429QuotaExhaustedThe Agent trial quota has been exhausted.诊断
500InternalErrorAn internal server error occurred.诊断
502UpstreamServiceErrorThe upstream Agent runtime failed to complete the request.诊断
503ServiceUnavailableThe service is temporarily unavailable.诊断

变更历史

暂无变更历史

补充说明

排查与重试

  • 未建立 SSE 时按 HTTP 状态和错误码表处理；AccessKey 签名认证与 Customer 实例密钥校验不同。
  • 参数错误、服务未开通、额度不足、会话冲突，先修正条件再调用。图片过期或无权限时更换有效链接。
  • 流内错误按 qi_event.retryable 判断是否退避重试；不要把 HTTP 200 或 [DONE] 单独当作成功。
  • 反馈问题时提供时间、接口名、qi_request_id 和网关 RequestId，不要提供密钥、完整签名链接或敏感输入。
Qwen Intelligence home page
什么是Qwen Intelligence
Mobile Planner Agent 规划智能体
Mobile-Use Agent 手机操作智能体
Creative Agent 创作智能体