Skip to main content
千问智能 home page
Creative Agent 创作智能体

API 参考

创作智能体流式调用的请求参数、响应事件与错误码

调用已发布的创作智能体实例，并通过 SSE 流式接收执行进度和图片结果。轻量版根据是否提供参考图执行图片生成或编辑；标准版先理解目标并规划任务，再完成生成或编辑，支持多轮会话。
API 版本：2026-08-31。调用前请先完成实例创建、配置与发布。

接口说明

接入前提

  • 已开通创作智能体服务，并准备已发布的实例 ID 和对应的实例访问密钥。
  • 使用阿里云 SDK 或 OpenAPI 签名方式完成 AccessKey 认证。
  • 实例访问密钥通过 X-QI-Agent-Api-Key 请求头传入，不能替代 AccessKey 签名。
  • 请求体使用 JSON 格式，并设置 Content-Type: application/json 和 Accept: text/event-stream。
  • 本接口仅支持流式响应，stream 必须设置为 true。

调用方式

项目说明
请求方法POST
请求路径/aigc/v1/chat/completions
请求格式application/json
返回格式text/event-stream
通过 X-QI-Instance-Id 指定实例，服务按照该实例已发布的配置执行。请求体中的 model 仅为兼容字段，不能用于切换实例模型。

会话管理

首轮请求可省略 X-QI-Session-Id。请从 SSE 正文中保存服务端返回的 qi_session_id，后续轮次回传同一值。
  • 不同会话使用不同的会话标识。
  • 同一会话中的请求应按顺序发送，避免并发修改会话状态。
  • 会话标识最长 128 个字符，可使用字母、数字、点、下划线、冒号和连字符。

授权信息

为 RAM 用户或 RAM 角色授权时，可在权限策略的 Action 元素中使用以下操作：
操作资源类型条件关键字关联操作
maasqiservice:AigcChatCompletionStream全部资源无无
请通过 RAM 访问控制完成授权。控制台用户也可以使用系统策略 AliyunMassQIConsoleFullAccess 获取千问智能控制台完整访问权限。

请求语法

POST /aigc/v1/chat/completions HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
X-QI-Agent-Api-Key: <INSTANCE_API_KEY>
X-QI-Instance-Id: <INSTANCE_ID>
X-QI-Session-Id: <SESSION_ID>
X-QI-Session-Id 仅在续接已有会话时传入。

请求参数

请求头

字段类型必填说明
X-QI-Agent-Api-Keystring是实例访问密钥，必须属于本次调用的创作智能体实例。请勿公开或写入客户端代码。
X-QI-Instance-Idstring是已发布的创作智能体实例 ID，必须与实例访问密钥对应。
X-QI-Session-Idstring否会话标识。首轮可省略，后续轮次回传 SSE 中的 qi_session_id。

请求体

字段类型必填说明
modelstring否兼容字段，可省略或传空字符串，不能用于切换实例模型。
messagesarray<object>是对话消息数组。服务取最后一条 user 消息作为当前目标，并结合会话历史执行。
metadataobject否本次图片创作的扩展参数。
streamboolean是必须设置为 true。
stream_optionsobject否流式响应选项。

messages

字段类型必填说明
messages[].rolestring是消息角色。当前创作目标使用 user；历史消息可包含 user、assistant 或 tool。
messages[].contentstring | array<object>是可直接传入文本，也可使用多模态内容数组。最后一条 user 消息必须包含非空文本。
messages[].content[].typestring是内容类型：text、image_url 或 video_url。
messages[].content[].textstring条件必填当 type 为 text 时，填写图片生成或编辑目标。
messages[].content[].image_url.urlstring条件必填当 type 为 image_url 时，填写可访问的 HTTPS 地址或完整 Base64 Data URL。
messages[].content[].video_url.urlstring条件必填当 type 为 video_url 时填写视频地址。仅标准版支持视频输入。
参考图片的签名地址必须在任务执行期间保持有效。轻量版不支持视频输入；最后一条 user 消息必须包含文字目标。

metadata.parameters

字段类型必填说明
sizestring否输出像素尺寸，例如 1024*1024、1280*720，也支持 1024x1024。请使用实例模型支持的宽高。
ninteger否本次生成图片数量，取值范围为 1～6。
seedinteger否随机种子，取值范围为 0～2147483647。
negative_promptstring否负向提示词，用于描述不希望出现在结果中的内容。
num_inference_stepsinteger否推理迭代次数，取值范围为 1～200。
guidance_scalenumber否引导强度，取值范围为 0～20。
metadata.parameters 仅支持表中字段。省略字段时使用实例的默认配置；不支持通过 response_format 切换输出格式。

stream_options

字段类型必填说明
include_usageboolean否设置为 true 时，在结束标记前返回独立的用量事件。Token 用量不代表图片张数或最终账单。

请求示例

文本生成图片

{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "生成一张极简蓝色圆形图标，不要文字或水印"
        }
      ]
    }
  ],
  "metadata": {
    "parameters": {
      "size": "1024*1024",
      "n": 1,
      "seed": 42,
      "num_inference_steps": 8,
      "guidance_scale": 0
    }
  },
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

参考图编辑

在同一条 user 消息中同时提交文字目标和参考图片： 
{
  "model": "",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "保持圆形图标不变，把蓝色改为绿色，不要文字或水印"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/reference.png"
          }
        }
      ]
    }
  ],
  "stream": true
}
轻量版在没有参考图时执行图片生成，有参考图时执行图片编辑；标准版会先规划任务，再完成对应创作。执行方式由实例规格和已发布配置决定。

返回说明

SSE 读取规则

响应的 Content-Type 为 text/event-stream。事件以空行分隔，每条数据事件以 data: 开头： 
data: {JSON}

data: [DONE]
客户端需要注意：
  • 一次网络读取不一定包含一条完整事件，应缓存并按空行切分。
  • 忽略以冒号开头的心跳注释。
  • 按顺序解析 data: 后的 JSON。
  • 收到 [DONE] 后停止读取，但不能只凭 [DONE] 判断任务成功。
  • HTTP 状态为 200 时仍可能通过 qi_event 返回执行错误。

数据字段

字段说明
id流式响应标识。
created创建时间，Unix 秒。
object固定为 chat.completion.chunk。
model兼容字段，返回空字符串。
qi_session_id会话标识，保存后可用于多轮续接。
qi_request_idAgent 执行请求标识，用于问题排查。
choices[0].delta.content正文增量，按事件顺序拼接。
choices[0].delta.artifacts图片结果，包含 id、kind、url、media_type 和 output_index。
choices[0].finish_reason内容结束原因，常见值包括 stop、tool_calls 和 length。
qi_event任务进度或错误信息，不应拼接到正文。
usageToken 用量。仅在 include_usage 为 true 时独立返回。
图片结果地址可能带有有效期，请在地址失效前保存需要长期使用的图片。

事件顺序

一次请求通常按以下顺序返回： 
角色或内容事件
→ 进度事件
→ 图片制品
→ finish_reason
→ [可选] usage
→ [DONE]
事件数量和分片边界不固定。进度事件可用于展示当前状态，但不要写死阶段数量。

流内错误

当 qi_event.type 为 error 时，表示任务执行失败。应读取以下字段：
字段说明
stage发生错误的阶段。
code错误码。
http_status对应的 HTTP 状态。
message错误说明。
retryable是否建议重试。
param相关参数，部分错误返回。
reason详细原因，部分错误返回。
data: {"qi_event":{"type":"error","stage":"input_validation","code":"invalid_parameter","http_status":400,"message":"The reference image URL has expired.","retryable":false,"reason":"image_url_expired"}}

data: [DONE]

错误码

HTTP 状态码错误码含义处理建议
400ContentFilter请求被内容安全策略拦截。调整输入内容后重试。
400InvalidParameter请求参数不合法。根据参数表检查字段类型、范围和必填项。
401InvalidApiKey实例访问密钥无效。检查密钥是否属于当前实例，并确认密钥未失效。
403ServiceNotActivated当前账号未开通所需服务。先在控制台开通服务。
404InvalidAgentNotFound未找到已发布的实例。检查实例 ID，并确认实例配置已发布。
409IdempotencyConflict相同请求标识被用于不同参数。使用新的请求标识重新调用。
409SessionConflict会话状态与当前请求冲突。确保同一会话内的请求按顺序发送。
413RequestEntityTooLarge请求体过大。减少输入内容或参考素材大小。
429QuotaExhausted可用额度已耗尽。检查实例额度或联系服务方扩容。
500InternalError服务内部错误。稍后重试；持续失败时提交请求标识排查。
502UpstreamServiceError上游运行服务未完成任务。根据 retryable 判断是否退避重试。
503ServiceUnavailable服务暂时不可用。稍后重试。

排查与重试

  • SSE 建立前的失败，按照 HTTP 状态和错误码处理。
  • SSE 建立后的失败，以 qi_event 为准，不能将 HTTP 200 视为任务成功。
  • 参数错误、服务未开通、额度不足或会话冲突，应先修正问题再调用。
  • 图片地址过期或无权限时，重新上传图片或提供新的有效地址。
  • 可重试错误建议采用退避策略，避免短时间内连续请求。
  • 反馈问题时提供发生时间、qi_request_id 和网关请求标识，不要提供密钥、完整签名链接或敏感输入。

变更历史

日期API 版本变更内容
2026-09-152026-08-31首次发布流式调用文档。
千问智能 home page
Plan Agent 规划智能体
Mobile Use Agent 手机操作智能体
Creative Agent 创作智能体
Memory & Proactive Agent
端侧 SDK
二方生态 Agent