> ## Documentation Index > Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 创建技能 > 通过 `.zip` 或 `.skill` 包上传创建项目拥有的技能及其第一个不可变版本。 - 包大小不超过 64 MiB（展开后 128 MiB、256 个文件），且必须恰好包含一个 SKILL.md，其 frontmatter 声明 `name` 与 `description`。 - 该名称不得属于项目中另一个活跃技能（409 `conflict_error`）。归档技能会释放其名称。 ## OpenAPI ````yaml /openapi-hosted-agents.yaml post /v1/skills openapi: 3.1.0 info: title: Kimi 托管智能体 version: 2026-09-01-beta description: >- Kimi 托管智能体的公共 REST API。 ## 认证 每个操作都使用 `Authorization: Bearer sk-...` 认证。不要在其他请求头中发送 API 凭据。 ## 资源标识符 资源 ID 是带资源专属前缀的不透明字符串。客户端应将 ID 作为完整值使用，不要解析后缀。 ## 核心概念 **智能体（Agent）**是版本化的智能体配置。**会话（Session）**是绑定到冻结智能体版本的一次进行中的对话。会话运行在一个协调者**线程**上，线程可以把工作委托给子线程。线程的每个轮次都会向会话事件流发送事件。 **凭据库（Vault）**持有项目级凭据，秘密值为只写。**环境（Environment）**描述会话运行所在的云沙箱。**记忆库（Memory Store）**是项目级文件存储，挂载进会话。**梦境（Dream）**是平台对一个记忆库执行的记忆维护。 **触发器（Trigger）**按计划或手动启动会话，每次执行记录为一次 **TriggerRun**。**产物（Artifact）**是会话交付的可下载文件。**插件（Plugin）**为智能体打包 MCP 服务器与技能。 **协调者**是会话的主线程，用户输入先到达它。模型提供方操作中的 `provider binding` 指调用方为该提供方配置的接入。 ## 版本控制 `kimi-api-version` 请求头选择本次请求使用的 API 版本（`YYYY-MM-DD`，与每个规范修订版的 `info.version` 对应）。未知值将被拒绝，返回 400 `invalid_request_error`。若要使用本文档所述版本，请在请求中携带 `kimi-api-version: 2026-09-01-beta`。省略请求头时，兼容行为仅适用于 `/v1/files*`：上传与删除将返回 200（而非 201/204），文件记录使用 `status`、`status_details` 字段（而非 `extract_status`），且上传的文件不能挂载到会话。其他端点均按本文档契约处理。 **破坏性变更只会随新的带日期版本发布。** 破坏性变更包括： - 删除或重命名端点、字段或枚举值 - 改变字段的类型或含义 - 新增必填请求字段或收窄可接受的输入 - 改变默认行为 - 删除错误类型或改变其含义 非破坏性变更（可随时发布；客户端必须容忍）：新端点、新的可选请求字段、新的响应字段或响应头、响应侧枚举中的新值（包括错误类型词汇表）、新的错误类型，以及文档或消息措辞更新。 带 `-beta` 后缀的版本是预览版：行为仍可能调整、不承诺完全兼容，但调用方可见的变更会在 ChangeLog 与发布说明中通知。稳定版在其后继版本发布后仍然可用。退役会提前在发布说明中公告，但不承诺固定窗口。版本进入退役状态后，其响应会携带 `Deprecation: true` 和 `Sunset: ` 响应头。Sunset 日期之后，该退役值会被视为未知值而拒绝。 ## 幂等 创建操作（创建资源或触发运行的 `POST` 端点）接受可选的 `Idempotency-Key` 请求头（最长 255 个字符；UUID 是不错的选择）。第一个请求的响应会保存 24 小时，作用域限定在你的项目和该端点：用相同的键和相同的请求体重试，会原样重放该响应（状态码和响应体）而不会重新执行。用不同的请求体复用同一个键，或在第一个请求仍在处理中时复用，返回 409 `conflict_error`。校验失败（400）和服务器错误（5xx）从不会被保存，因此重试这些请求总是安全的。键在 24 小时后过期，之后被视为新键。 ## 错误 所有非 2xx 响应共用一个错误响应 JSON 格式：`{"error": {type, message, request_id, param?}}`。每个响应（无论成功还是错误）都携带 `Msh-Request-Id` 响应头，其值与错误体中的 `request_id` 一致。 `error.type` 是一个包含 10 个值的封闭词汇表——每个值对应一种客户端恢复策略，且各自固定映射到一个 HTTP 状态码： | 错误类型 | 状态码 | 含义 → 恢复方式 | | --- | --- | --- | | `invalid_parameter_error` | 400 | 某个字段未通过校验。`param` 指出该字段——修复字段后重试 | | `invalid_request_error` | 400 | 请求本身格式错误（无法解析的请求体、错误的方法、请求体过大、未知的 API 版本）——修复请求 | | `failed_precondition_error` | 400 | 资源当前状态不允许该操作——先改变状态（消息中说明了方法） | | `authentication_error` | 401 | 凭据缺失或被拒绝——重新认证 | | `permission_denied_error` | 403 | 已认证但无权限——不要重试，检查凭据所属项目与权限 | | `resource_not_found_error` | 404 | 资源不存在或不可见——检查 id | | `conflict_error` | 409 | 唯一键冲突或并发修改——重命名，或重新加载后重试 | | `rate_limit_reached_error` | 429 | 瞬时速率限制——在 `Retry-After` 之后重试 | | `exceeded_current_quota_error` | 429 | 配额或预算耗尽——配额或预算增加后再重试 | | `server_error` | 500 | 平台内部故障，包括暂时不可用——通用消息。退避（1s → 2s → 4s）后重试 | 可定位到字段的失败始终是带 `param` 的 `invalid_parameter_error`。无法归咎于单一字段的失败是不带 `param` 的 `invalid_request_error`。只有 `rate_limit_reached_error` 携带 `Retry-After`。 嵌入资源内部的错误字段（例如 `TriggerRun.error`）复用同一错误响应 JSON，但其 `type` 是领域专属的分类（例如 `fire_failed`），不属于上述 10 个值——仅用于展示。客户端必须容忍未知值。 ## 会话执行错误 `session_error` 事件报告已创建会话期间发生的失败。它不是 HTTP 错误响应。其 `error_type` 使用独立于 HTTP `error.type` 的封闭词表： | `error_type` | 含义 → 恢复方式 | | --- | --- | | `internal_error` | 未归类的平台内部错误——联系支持并提供 request_id | | `model_error` | 模型服务出错——按 message 处理或稍后重试 | | `model_unavailable` | 当前 Session 的模型路由不可用——重新创建 Session | | `rate_limited` | 模型请求被限流——稍后重试 | | `engine_overloaded` | 模型引擎暂时过载——稍后重试 | | `quota_exceeded` | 模型配额耗尽或账户欠费——充值后发送新消息继续 | | `context_length_exceeded` | 对话超出模型上下文窗口——缩短输入或新建 Session | | `invalid_request` | 请求被模型拒绝——按 message 修改请求 | | `timeout` | 模型请求超时——稍后重试 | | `max_steps` | 本轮达到步数上限——发送新消息继续 | 这些值描述失败的模型轮次，其 message 会给出下一步操作。客户端必须将该事件与 HTTP `error.type` 分开处理。 ## 分页 列表操作接受 `page_size`（1–1000，默认 50）和不透明的 `page_token`，返回 `{items, next_page_token}`。`next_page_token` 缺失表示已到最后一页。 ## 速率限制与大小上限 请求可能受到速率限制。被限流的请求返回 429 `rate_limit_reached_error`，`Retry-After` 的值是需要等待的秒数。`exceeded_current_quota_error` 仅表示配额或预算耗尽，不携带该响应头。请求体按路由类别设有上限。超限返回 400 `invalid_request_error`，没有 413： | 路由 | 请求体上限 | | --- | --- | | JSON 端点（下列除外） | 4 MiB | | 记忆写入路由 | 28 MiB | | `POST /v1/files` | 每个文件 100 MiB | | `POST /v1/skills` | 每个 Skill 包 64 MiB | ## 事件流（SSE） Session 和线程事件流（`GET .../events/stream`）将事件封装为：`event:` = 事件类型，`id:` = 恢复游标，`data:` = 完整的事件 JSON，并每 30 秒发送一个 `: hb` 心跳。流建立之前发生的失败返回标准错误响应 JSON。流中途发生的失败以一个携带相同错误响应 JSON 的终止帧 `event: error` 到达，随后流关闭。重连时，以最后收到的帧 `id` 作为 `cursor`（或使用 `Last-Event-ID` 头）。不可用的游标返回 `invalid_parameter_error` 且 `param=cursor`：修正它，或从保留的起点重新订阅。如果消息提示游标已过期（其位置已被回收），丢弃已有的部分预览，打开 `cursor=now` 流并等待控制帧，通过 `GET .../events` 补齐数据，然后继续实时流。 ## Files 更新 上传、浏览、下载和删除用户文件。 - 新增 `kimi-api-version` 请求头：传与不传对应两套不同的 API 规格。只有 ID 带 `file_` 前缀的文件才能用于 Hosted Agents。 - 提升文档解析能力：优化表格、公式等复杂文档内容的解析效果。 - 调整图片处理方式：图片不再进行 OCR 文本提取。 - 自动处理同名文件：上传与已有文件同名的文件时，服务端自动为新文件重命名，避免文件名冲突。 - 调整文件删除机制：文件删除后，仍可能残留在活跃会话的工具调用中。 ## ChangeLog servers: - url: https://api.moonshot.cn description: 生产环境 variables: {} security: - BearerAuth: [] tags: - name: 智能体 description: 管理智能体配置及其版本。 - name: 会话 description: 管理会话、线程、资源、消息和事件。 - name: 文件 description: 上传、浏览、下载和删除用户文件。 - name: 产物 description: 查看已交付的产物，下载指定版本。 - name: 技能 description: 管理 Skill 包及不可变版本。 - name: 环境 description: 管理执行环境及其配置。 - name: 凭据库 description: 管理凭据库、凭据和 OAuth 会话。 - name: 插件 description: 列出并查看可用插件。 - name: 记忆库 description: 管理记忆库、文件、版本和梦境策略。 - name: 触发器 description: 创建、管理和运行 Trigger。 paths: /v1/skills: post: tags: - 技能 summary: 创建技能 description: >- 通过 `.zip` 或 `.skill` 包上传创建项目拥有的技能及其第一个不可变版本。 - 包大小不超过 64 MiB（展开后 128 MiB、256 个文件），且必须恰好包含一个 SKILL.md，其 frontmatter 声明 `name` 与 `description`。 - 该名称不得属于项目中另一个活跃技能（409 `conflict_error`）。归档技能会释放其名称。 operationId: createSkill parameters: - name: Idempotency-Key in: header required: false description: 可选的幂等键。相同的键与请求体会在 24 小时内重放首个响应；以不同的请求体复用，或在首个请求仍在处理时复用，返回 409。 schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: allOf: - $ref: '#/components/schemas/BinaryContent' description: 技能包归档。 required: - file encoding: file: contentType: text/plain example: {} responses: '201': description: 已创建的技能及其首个不可变版本。 content: application/json: schema: $ref: '#/components/schemas/CreateSkillResponse' example: skill: id: skill_01h455vb4pex5vsknk084sn02q name: data-analysis description: 分析表格数据并生成摘要。 latest_version: '1' status: active created_at: '2026-08-01T10:00:00.000Z' updated_at: '2026-08-01T10:00:00.000Z' scope: project version: skill_id: skill_01h455vb4pex5vsknk084sn02q version: '1' name: data-analysis description: 分析表格数据并生成摘要。 created_at: '2026-08-01T10:00:00.000Z' '400': description: >- 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: BinaryContent: type: string description: multipart 上传中文件部分的原始字节。 format: binary CreateSkillResponse: type: object required: - skill - version properties: skill: $ref: '#/components/schemas/Skill' description: 新创建的技能。 version: $ref: '#/components/schemas/SkillVersion' description: 根据提交的软件包创建的第一个不可变版本。 description: 创建技能的结果：目录资源及其第一个版本。 BadRequestErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: >- 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 UnauthorizedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 凭据缺失或被拒绝。 ConflictErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 TooManyRequestsErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 已达速率限制或配额耗尽。 APIError: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 错误详情。 description: 所有非 2xx 响应共用的标准错误响应 JSON 格式。 Skill: type: object required: - id - name - description - latest_version - status - created_at - updated_at - scope properties: id: type: string description: 技能 ID。 name: type: string description: >- 目录名称，是稳定的挂载与面向模型的标识符。同一项目内处于 active 状态的项目自有技能名称必须互不相同。归档技能会释放其名称，供后续技能使用。 description: type: string description: 向调用方展示的目录描述。 latest_version: type: string description: 当前可用的最新不可变版本（`"1"`、`"2"`……）。 status: $ref: '#/components/schemas/SkillStatus' description: 当前的目录状态。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。 display_name: type: string description: 向用户展示的技能名称。 icon_url: type: string description: 官方技能可选提供的图标 URL。 description: 稳定的技能身份。项目技能的元数据和包在创建时固定，官方技能的展示字段可由管理员维护。 SkillVersion: type: object required: - skill_id - version - name - description - created_at properties: skill_id: type: string description: 所属技能的 ID。 version: type: string description: 此 Skill 内 Hosted Agents 分配的不可变版本标识符（`"1"`、`"2"`……）。 name: type: string description: 此版本的 SKILL.md 声明的技能名称。 description: type: string description: 此版本的 SKILL.md 声明的技能描述。 created_at: type: string format: date-time description: 此版本的创建时间。 description: 技能的一个不可变包快照。 ErrorObject: type: object required: - type - message properties: type: $ref: '#/components/schemas/ErrorType' description: 来自注册词汇表的机器可读错误类型。 message: type: string description: 人类可读的错误消息。 param: type: string description: 适用时，为与错误相关的请求参数或请求体字段。在 `invalid_parameter_error` 上始终存在。 request_id: type: string description: >- 服务端分配的请求标识符，用于支持查询。在错误响应上始终存在（与 `Msh-Request-Id` 头一致），在嵌入资源内部的错误详情中缺省。 description: 所有 API 版本共用的机器可读错误详情。 SkillStatus: type: string enum: - active - archived description: 技能当前的目录状态。 ResourceScope: type: string enum: - official - org - project - user description: 资源的可见范围。`official` 资源由平台提供，通过本 API 只读。 ErrorType: type: string enum: - invalid_parameter_error - invalid_request_error - failed_precondition_error - authentication_error - permission_denied_error - resource_not_found_error - conflict_error - rate_limit_reached_error - exceeded_current_quota_error - server_error description: >- 已注册的机器可读错误类型，每种客户端恢复策略对应一个。该集合对客户端封闭，可穷尽处理，但响应侧保持开放：客户端必须容忍未来新增的取值（新增取值不属于破坏性变更）。 securitySchemes: BearerAuth: type: http scheme: Bearer ````