AI 生成技能

提交技能草稿并接收服务端发送的润色事件。结果事件包含可保存的技能内容。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/skills/polish/stream

调用前准备

准备个人访问令牌、工作区 ID 和待润色的技能草稿。响应类型为 text/event-stream。

请求体

输入示例

curl -N -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills/polish/stream" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "摘要",
    "description": "生成内容摘要",
    "instruction": "总结输入内容"
  }'

参数说明

参数	类型	是否必填	说明
name	string	是	技能名称。
instruction	string	是	待润色的技能指令。
description	string	是	技能说明。
instruction_spec	object	否	结构化技能指令。
instruction_spec.body	string	否	当前接口忽略此字段。待润色正文请填写 instruction。
instruction_spec.variables_schema	object	否	指令变量的 JSON Schema。
input_requirements	string	否	输入要求。
output_format	string	否	输出格式。
category	string	否	技能分类。
tags	string（字符串数组）	否	技能标签。
phase	string	否	技能阶段。
pipeline	string（字符串数组）	否	流水线步骤。
pipeline_ref	string	否	流水线引用。
source_type	string	否	技能源类型。
source_ref	string	否	技能源引用。
routing_summary	object	否	路由摘要。
requirements	object	否	技能依赖要求。
parameters_schema	object	否	输入参数的 JSON Schema。
output_contract	object	否	输出格式约定。
labels	object	否	字符串标签。
annotations	object	否	字符串注解。
metadata	object	否	扩展元数据。

成功响应

响应示例

event: started
data: {"request_id":"req_01","prompt_version":"skill_polish_v1"}

event: delta
data: {"request_id":"req_01","content":"请总结输入内容"}

event: ping
data: {"request_id":"req_01","timestamp":"2026-08-21T07:00:00Z"}

event: result
data: {"request_id":"req_01","result":{"name":"摘要","description":"摘要技能","instruction":"请总结输入内容","instruction_spec":{"body":"请总结输入内容"},"routing_summary":{},"requirements":{},"tags":[]}}

event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}

字段说明

成功时返回事件流。每个事件都由 event: 行、单行 JSON 的 data: 行和一个空行组成。result 事件包含已校验的技能草稿，done 表示流结束。

通用字段

字段	类型	说明
SSE 事件名	string	event: 行中的事件类型，可为 started、delta、ping、result、error 或 done。
request_id	string	本次润色请求 ID。

开始事件

字段	类型	说明
prompt_version	string	started 事件中的提示词版本。

增量与心跳

字段	类型	说明
content	string	delta 事件中的增量文本。
timestamp	string	ping 事件中的 RFC 3339 时间。

生成结果

字段	类型	说明
result	object	result 事件中的已校验技能草稿。
result.name	string	技能名称。
result.description	string	技能说明。
result.instruction	string	润色后的技能指令。
result.instruction_spec	object	结构化技能指令，正文与 instruction 相同。
result.input_requirements	string	输入要求。未设置时不返回。
result.output_format	string	输出格式。未设置时不返回。
result.category	string	技能分类。未设置时不返回。
result.tags	string（字符串数组）	技能标签。
result.phase	string	技能阶段。未设置时不返回。
result.pipeline	string（字符串数组）	流水线步骤。未设置时不返回。
result.pipeline_ref	string	流水线引用。未设置时不返回。
result.source_type	string	技能源类型。未设置时不返回。
result.source_ref	string	技能源引用。未设置时不返回。
result.routing_summary	object	路由摘要对象，可为空对象。
result.requirements	object	技能依赖对象，可为空对象。
result.parameters_schema	object	输入参数的 JSON Schema。未设置时不返回。
result.output_contract	object	输出格式约定。未设置时不返回。
result.labels	object	字符串标签。未设置时不返回。
result.annotations	object	字符串注解。未设置时不返回。
result.metadata	object	扩展元数据。未设置时不返回。
result.pending_confirmations	string（字符串数组）	仍需确认的事项。没有时不返回。
result.warnings	string（字符串数组）	润色警告。没有时不返回。

错误事件

字段	类型	说明
error	object	error 事件中的公开错误信息。
error.code	string	流内错误代码。
error.message	string	流内错误说明。
error.retryable	boolean	是否可以重试。

错误响应

建立事件流前，权限拒绝返回 HTTP 403、code=5。无法建立事件流或未知内部错误返回 HTTP 500、code=13。事件流建立后，应读取流内错误和结束事件，不能仅凭 HTTP 200 判断成功。

响应示例

event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}

{
  "code": 2,
  "message": "invalid argument"
}

字段说明

流已经开始后，处理错误通过 SSE error 事件返回，随后发送 done：

流建立前的请求错误使用普通 JSON 响应：

通用字段

HTTP 状态码	错误代码	说明
400	2	**常见原因：**JSON 无效，或技能草稿未通过建立事件流前的校验。**建议操作：**检查请求体和必填字段。
503	15	**常见原因：**技能润色服务未配置。**建议操作：**稍后重试。

最后更新于 2026 年 10 月 19 日