Skip to main content

Skill API 概览

Skill API 用于管理百炼上的 Skill,支持创建、查询、删除 Skill 及管理版本。

Skill API 用于管理阿里云百炼上的 Skill,覆盖自定义 Skill 与官方 Skill 的创建、查询、删除,以及版本上传、查询和下载。
调用前请先配置认证;错误处理见Skill API 错误码。

前提条件

  1. 已开通阿里云百炼,并创建 API Key。
  2. 已获取工作空间 ID。登录百炼控制台,在右上角工作空间菜单中复制工作空间 ID。

Endpoint

https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/skills
  • workspace_id:工作空间 ID。

接口列表

接口方法说明
创建 SkillPOST /api/v1/skills上传 ZIP 包创建自定义 Skill
获取 SkillGET /api/v1/skills/{skill_id}查询单个 Skill
列出 SkillGET /api/v1/skills分页查询自定义和官方 Skill
删除 SkillDELETE /api/v1/skills/{skill_id}删除自定义 Skill 及其全部版本
创建版本POST /api/v1/skills/{skill_id}/versions为自定义 Skill 上传新版本
列出版本GET /api/v1/skills/{skill_id}/versions分页查询版本
获取版本详情GET /api/v1/skills/{skill_id}/versions/{version}查询指定版本
下载版本 ZIPGET /api/v1/skills/{skill_id}/versions/{version}/content获取 ZIP 包的临时下载地址

响应结构

成功和业务错误统一返回以下结构:
字段类型说明
successboolean请求是否成功
error_codestring / null错误码,成功时为 null
error_msgstring / null错误信息,成功时为 null
dataobject / array / null业务数据,失败时为 null
request_idstring请求 ID,同时通过响应头 X-Request-Id 返回
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {},
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

分页

Skill 列表和版本列表使用页码分页。
参数类型默认说明
pageNointeger1页码,最小 1
pageSizeinteger20单页条数,取值范围 1 到 100
pageNo × pageSize 不能超过 10000。响应返回 total、page_no、page_size,调用方据此计算总页数。

枚举

status
值说明
checking安全扫描中,暂不可用
active可用
rejected未通过安全扫描,不可用
deleted已删除,正常查询不返回
source
值说明
customer主账号和工作空间下的自定义 Skill
official官方 Skill

数据结构

SkillDTO

创建 Skill、获取 Skill 和 Skill 列表返回此对象。
字段类型说明
idstringSkill 唯一标识,用作路径参数 skill_id
display_namestring展示名称;为空时取 SKILL.md 的 name
display_descriptionstring展示描述;为空时取 SKILL.md 的 description
sourcestringcustomer 或 official
statusstringSkill 主记录状态,见上表
latest_versionstring最新版本号,例如 1.0
classificationstring / null分类;官方 Skill 有值,自定义 Skill 为 null
meta_infoobject / null官方 Skill 的元信息;自定义 Skill 为 null
created_atstring创建时间,ISO 8601 UTC
updated_atstring更新时间,ISO 8601 UTC

SkillVersionDTO

创建版本、列出版本和获取版本详情返回此对象。
字段类型说明
idstring版本记录唯一标识,skillver_ 前缀
typestring固定为 skill_version
skill_idstring所属 Skill ID
display_namestring该版本的展示名称;为空时取该版本 SKILL.md 的 name
display_descriptionstring该版本的展示描述;为空时取该版本 SKILL.md 的 description
versionstring版本号,格式为 major.minor,例如 1.0、1.1
statusstring该版本状态,见上表
created_atstring创建时间,ISO 8601 UTC
updated_atstring更新时间,ISO 8601 UTC
additional_propertiesobject / null扩展属性;无内容时为 null
additional_properties 字段:
字段类型说明
error_infomap<string,string> / null安全扫描未通过时的明细,键为文件路径,值为问题描述

SkillDeletedResponse

字段类型说明
idstring被删除的 Skill ID
typestring固定为 skill_deleted

VersionDownloadResponse

字段类型说明
skill_idstringSkill ID
versionstring版本号
file_urlstringZIP 包的预签名下载地址,有效期 2 小时

Page

Skill 列表和版本列表的 data 结构。
字段类型说明
itemsarray当前页记录
totallong命中总数
page_nointeger当前页码
page_sizeinteger单页条数

可见性

按 skill_id 访问的接口先校验可见性,不可见时按不存在处理。
对象自定义 Skill官方 Skill
Skill主账号和工作空间下未删除的记录未删除且状态为 active
版本未删除的全部状态,包含 checking 和 rejected仅 active