The Skill API manages Skills in Model Studio, including Skill creation, queries, deletion, and version management.
The Skill API manages Skills in Alibaba Cloud Model Studio. It covers creating, querying, and deleting custom and official Skills, as well as uploading, querying, and downloading versions.
Successful responses and business errors share the following structure:
The Skill list and version list use page-based pagination.
status
source
Returned by create, get, and list operations.
Returned by create version, list versions, and get version operations.
The
APIs that access a resource by
Configure authentication before calling the API. For error handling, see Skill API error codes.
Prerequisites
- Alibaba Cloud Model Studio is activated, and an API key is created.
- A workspace ID is available. Log on to the Model Studio console, and copy the workspace ID from the workspace menu in the upper-right corner.
Endpoint
workspace_id: the workspace ID.
API list
| API | Method | Description |
|---|---|---|
| Create a Skill | POST /api/v1/skills | Creates a custom Skill from a ZIP package |
| Get a Skill | GET /api/v1/skills/{skill_id} | Gets a Skill |
| List Skills | GET /api/v1/skills | Lists custom and official Skills with pagination |
| Delete a Skill | DELETE /api/v1/skills/{skill_id} | Deletes a custom Skill and all its versions |
| Create a version | POST /api/v1/skills/{skill_id}/versions | Uploads a new version for a custom Skill |
| List versions | GET /api/v1/skills/{skill_id}/versions | Lists versions with pagination |
| Get version details | GET /api/v1/skills/{skill_id}/versions/{version} | Gets a version |
| Download a version ZIP | GET /api/v1/skills/{skill_id}/versions/{version}/content | Gets a temporary download URL for the ZIP package |
Response structure
Successful responses and business errors share the following structure:
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded |
| error_code | string / null | Error code. null on success |
| error_msg | string / null | Error message. null on success |
| data | object / array / null | Business data. null on failure |
| request_id | string | Request ID, also returned in the X-Request-Id response header |
Pagination
The Skill list and version list use page-based pagination.
| Parameter | Type | Default | Description |
|---|---|---|---|
| pageNo | integer | 1 | Page number. Minimum 1 |
| pageSize | integer | 20 | Number of items per page. Valid values: 1 to 100 |
pageNo × pageSize cannot exceed 10000. The response returns total, page_no, and page_size.
Enumerations
status
| Value | Description |
|---|---|
| checking | Security scanning in progress. Not available |
| active | Available |
| rejected | Failed the security scan. Not available |
| deleted | Deleted. Not returned by normal queries |
| Value | Description |
|---|---|
| customer | Custom Skill under the primary account and workspace |
| official | Official Skill |
Data structures
SkillDTO
Returned by create, get, and list operations.
| Field | Type | Description |
|---|---|---|
| id | string | Unique Skill ID. Used as the skill_id path parameter |
| display_name | string | Display name. If empty, the name in SKILL.md is used |
| display_description | string | Display description. If empty, the description in SKILL.md is used |
| source | string | customer or official |
| status | string | Skill status. See the enumeration above |
| latest_version | string | Latest version number, such as 1.0 |
| classification | string / null | Classification. Set for official Skills; null for custom Skills |
| meta_info | object / null | Metadata for official Skills; null for custom Skills |
| created_at | string | Creation time in ISO 8601 UTC |
| updated_at | string | Update time in ISO 8601 UTC |
SkillVersionDTO
Returned by create version, list versions, and get version operations.
| Field | Type | Description |
|---|---|---|
| id | string | Unique version ID. Prefixed with skillver_ |
| type | string | Always skill_version |
| skill_id | string | ID of the parent Skill |
| display_name | string | Display name of this version. If empty, the name in this version's SKILL.md is used |
| display_description | string | Display description of this version. If empty, the description in this version's SKILL.md is used |
| version | string | Version number in major.minor format, such as 1.0 or 1.1 |
| status | string | Version status. See the enumeration above |
| created_at | string | Creation time in ISO 8601 UTC |
| updated_at | string | Update time in ISO 8601 UTC |
| additional_properties | object / null | Additional properties. null if empty |
additional_properties fields:
| Field | Type | Description |
|---|---|---|
| error_info | map<string,string> / null | Details of a failed security scan. The key is a file path, and the value is the issue description |
SkillDeletedResponse
| Field | Type | Description |
|---|---|---|
| id | string | ID of the deleted Skill |
| type | string | Always skill_deleted |
VersionDownloadResponse
| Field | Type | Description |
|---|---|---|
| skill_id | string | Skill ID |
| version | string | Version number |
| file_url | string | Presigned download URL for the ZIP package. Valid for 2 hours |
Page
The data structure of the Skill list and version list.
| Field | Type | Description |
|---|---|---|
| items | array | Records on the current page |
| total | long | Total number of matching records |
| page_no | integer | Current page number |
| page_size | integer | Number of items per page |
Visibility
APIs that access a resource by skill_id check visibility first. Invisible resources are treated as nonexistent.
| Object | Custom Skill | Official Skill |
|---|---|---|
| Skill | Not deleted under the primary account and workspace | Not deleted and active |
| Version | All non-deleted versions, including checking and rejected | active only |