> ## 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. # 获取插件版本内容 > 下载项目自有插件指定确切发布版本的插件包归档。响应始终为 `application/zip`，字节与提交时的归档一致。`official` 插件不提供插件包下载，返回 400 `failed_precondition_error`。已归档的插件返回 404。 ## OpenAPI ````yaml /hosted-agents/openapi.yaml get /v1/plugins/{id}/versions/{version}/content openapi: 3.2.0 info: title: Kimi 托管智能体 version: 2026-09-01-beta description: >- ## 概览 Kimi 托管智能体提供公共 REST API，用于配置智能体、运行会话，以及读取事件和产物。 API 基础地址为 `https://api.moonshot.cn/v1`。本文操作路径已包含 `/v1`，拼接这些路径时使用服务器地址 `https://api.moonshot.cn`。 ### 资源模型 **智能体**（Agent）定义执行所需的模型、指令、工具等配置。**会话**（Session）将冻结的智能体版本与对话及执行历史关联起来。会话可以覆盖部分配置，无需修改智能体。 每个会话都有接收用户输入的协调者**线程**（Thread），可以将工作委托给独立执行的子线程。会话事件流包含子线程活动，通过 `session_thread_id` 区分事件所属线程。 其他资源提供执行条件或保存执行结果： - **环境**（Environment）提供云沙箱或自托管执行。自托管 worker 认领**工作行**（WorkItem），在租约有效期间执行沙箱工具调用。 - **凭据库**（Vault）保存项目级凭据，秘密值只写不读。 - **技能**（Skill）提供可复用指令；**插件**（Plugin）打包技能与 MCP 服务器。 - **记忆库**（Memory Store）保存会话可访问的项目级文件；**梦境**（Dream）维护这些记忆。 - **触发器**（Trigger）按计划或手动启动、复用会话，每次执行记录为一次 **TriggerRun**。 - **产物**（Artifact）是会话交付的可下载文件。 模型提供方操作中的 `provider binding` 指调用方为该提供方配置的接入。 ## 认证 通过 `Authorization` 请求头，以 Bearer 方式发送凭据。根据调用的操作选择凭据： | 凭据 | 授权范围 | | --- | --- | | API key（`sk-...`） | 调用方权限允许的项目 API。 | | 环境 work key | 绑定环境的工作队列。 | | 会话 work token | 绑定会话允许的 worker 操作。 | worker 凭据不能与 API key 互换，环境和会话凭据也不能互换。 例如，使用 API key 列出智能体： ```sh curl https://api.moonshot.cn/v1/agents \ -H "Authorization: Bearer $KIMI_API_KEY" \ -H "kimi-api-version: 2026-09-01-beta" ``` ## API 版本 ### 选择版本 发送 `kimi-api-version: 2026-09-01-beta` 使用本契约。除 `/v1/files*` 外，缺少版本头返回 400 `invalid_request_error`；所有端点都会拒绝未知版本。 文件端点允许省略版本头，以使用兼容格式：上传和删除返回 200，而非 201/204；文件记录使用 `status`、`status_details`，而非 `extract_status`；上传的文件不能挂载到会话。省略版本头不表示选择最新版。 ### 兼容性 稳定版的破坏性变更进入新的日期版本，包括删除或重命名端点、字段或枚举值，改变类型、含义或默认行为，新增必填请求字段，收窄合法输入，以及移除或重新定义错误类型。 客户端需要容忍新增端点、可选请求字段、响应字段、响应头和响应枚举值，包括错误类型。消息措辞不属于稳定接口。 ### Beta 与退役政策 当前版本是 beta，行为可能在同一版本内调整，调用方可见变化记录在 ChangeLog 和发布说明中。稳定版在继任版本发布后继续可用，退役提前公告，但没有固定通知期。退役政策约定响应携带 `Deprecation` 和 `Sunset`，到期后拒绝该版本。目前没有版本进入退役。 ## 请求约定 ### 资源标识符 资源 ID 是不透明字符串，应完整保存和传递。不要校验前缀、解析结构，或通过 ID 推断资源属性。 ### 请求体与更新 JSON 请求体使用 `application/json`，文件和包上传使用 `multipart/form-data`。未声明的内容类型返回 400 `invalid_request_error`。 只发送操作声明的字段，未知 JSON 字段返回 400 `invalid_parameter_error`。`PATCH` 中省略字段表示不修改，非 nullable 字段拒绝显式 `null`，清空时使用该字段说明中约定的空值。 ### 分页 列表操作接受 `page_size`（1–1000，默认 50）和 `page_token`，返回 `{items, next_page_token}`。将返回的令牌原样传入以读取下一页；`next_page_token` 缺省表示结束。 ## 幂等与创建重试 声明了 `Idempotency-Key` 的操作接受最长 255 字节的键。每个创建意图使用独立键，包括针对不同目标资源的创建。不要在同一项目内跨操作或资源复用键。 已保存的响应在 24 小时内按原状态码和响应体重放。重试时保持键和请求体字节一致，JSON 空白变化或重新生成 multipart boundary 都可能造成冲突。同键请求不同，或原请求仍在执行时，返回 409 `conflict_error`。 校验、认证与权限类失败和 5xx 不保存响应；业务拒绝可以被保存。没有重放记录不能证明写入未发生。超时、500 或键过期后，应先查询资源确认结果，再决定是否重新创建。幂等键减少重复执行，但不保证所有故障下都只写入一次。 ## 限流与大小限制 临时限流返回 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` | 每个技能包 64 MiB | | 插件包上传 | 每个插件包 64 MiB | ## 错误处理 ### HTTP 错误 API 错误使用 `{"error": {type, message, request_id, param?}}`。结合 HTTP 状态码和 `error.type` 选择恢复方式，用 `message` 展示原因，不要解析其措辞。 | 错误类型 | 状态码 | 恢复方式 | | --- | --- | --- | | `invalid_parameter_error` | 400 | 修正 `param` 指出的字段。 | | `invalid_request_error` | 400 | 修正请求格式、方法、版本或大小。 | | `failed_precondition_error` | 400、409、412 | 核对操作的状态要求。完成 WorkItem stop 时收到 409，应继续服务当前租约；租约操作返回 412，表示放弃过期租约并重新轮询。 | | `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 | 记录请求 ID，写操作先确认结果，读操作可退避重试。 | 表中是当前声明的类型。客户端也应处理未知类型和不符合该格式的响应，包括基础设施故障。 字段校验错误携带 `param`，路径可能包含位置前缀和数组下标，如 `body.mcp_servers[2].name`，也可能只有字段名。不要依赖单一路径形状。 资源中的错误字段，如 `TriggerRun.error`，使用各自的领域 schema 和仅供展示的类型，不是 HTTP 错误响应。 ### 请求 ID 响应携带 `Msh-Request-Id`，通常与错误体的 `request_id` 一致；重放可能保留原响应体的 ID，而响应头标识本次重试。反馈重试问题时请同时提供两个 ID。 ### 会话执行错误 `session.error` 事件描述会话创建后的执行问题，其 `error_type` 独立于 HTTP `error.type`。重新连接事件流不会重试执行。 | `error_type` | 恢复方式 | | --- | --- | | `internal_error` | 反馈错误并提供可用的请求 ID。 | | `model_error` | 按消息处理或稍后重试执行。 | | `model_unavailable` | 选择可用模型或新建会话。 | | `rate_limited` | 等待后重试执行。 | | `engine_overloaded` | 稍后重试执行。 | | `quota_exceeded` | 恢复模型配额或账户余额后继续。 | | `context_length_exceeded` | 缩短输入或新建会话。 | | `invalid_request` | 按消息修正模型请求。 | | `timeout` | 核对会话状态后再重试执行。 | | `max_steps` | 发送新输入，以新的轮次继续。 | | `mcp_connection_failed` | 检查受影响 MCP 服务器的连通性。 | | `mcp_authentication_failed` | 更新或重新连接受影响的 MCP 凭据。 | 客户端应容忍新增值，并在恢复前核对会话状态。MCP 失败可能只让该服务器的工具不可用，其余执行仍然继续。存在 `mcp_server_name` 时，可据此定位受影响的服务器。 ## 事件流（SSE） ### 事件格式 会话和线程事件流（`GET .../events/stream`）通过 `event:` 表示事件类型、`id:` 表示恢复游标、`data:` 提供完整事件 JSON，每 30 秒发送一次 `: hb` 心跳。 事件流按序投递完整事件；`agent.delta` 增量预览仅在 `include_deltas=true` 时发送。 建流前失败返回 HTTP 错误格式。建流后报告的传输失败通过 `event: error` 携带同一格式并关闭连接。客户端也应处理没有错误帧的断线。 ### 重连 以最后收到的帧 `id` 作为 `cursor` 或 `Last-Event-ID` 重连。资源事件 ID 不是恢复游标。不可用的游标返回 `invalid_parameter_error`，且 `param=cursor`。 ### 游标过期后的恢复 游标位置过期时，丢弃未完成的预览，并按以下顺序恢复： 1. 打开 `cursor=now` 流，等待控制帧，暂存随后到达的实时事件。 2. 通过 `GET .../events` 回补已持久化事件。 3. 合并历史与暂存事件，去除重叠，再继续消费已打开的流。 先建流再回补，可避免历史与实时事件之间留下空档。未写入持久历史的预览无法重建。 ## ChangeLog 以下按日期记录调用方可见变化，同日优先列出影响已有接入的变化，再列新增能力与仅更新契约的内容。每条说明影响及必要的调用方动作，完整输入与输出见对应操作定义。 ### 2026-10-14 #### 触发器 - **`reuse_session` 更新**：更新保持 `reuse_session` 的触发器时，修改 `agent_id`、`agent_version`、`environment_id` 或 `resources` 现在返回 400 `failed_precondition_error`。此前这些修改会被接受，但不会作用到托管会话，该会话沿用创建时的配置。需要修改时，先将 `session_mode` 切换为 `new_session`，或新建触发器。 - **平台发起的运行**：平台为托管触发器发起的运行（例如梦境策略的活跃度检查）现在记录 `context.type: "system"`，不再记录为归属触发器创建者的 `manual` 上下文。按 `context.type` 分支的客户端须接受 `system`。 #### 会话事件流 - **增量预览改为可选**：会话与线程事件流默认不再包含 `agent.delta` 事件。需要继续接收增量预览时，设置新增的 `include_deltas=true` 查询参数；只消费完整事件的调用方不再接收增量流量。 ### 2026-10-10 #### 自托管 worker 停止 - **worker 停止**：中断会话在取消完成后可以释放工作行，即使仍保留排队输入。租约释放后，显式 Continue 重新将工作入队。使用 `user.interrupt` 停止会话执行，使用工作行 stop 请求 worker 停止。 - **停止完成**：工作行 stop 不传 `final_status` 时进入 `stopping`；worker 取消工具、完成结果回写后提交 `final_status: completed`，仍忙碌的会话会被取消。空闲 worker 可以直接提交 `completed`，释放租约但不取消会话；活跃执行或新输入返回 409 `failed_precondition_error`。会话 work token 可以停止自己的工作行，REST 不接受 `force` 或 `reason`。 #### 工具确认与自定义工具 - **工具回复**：`always_ask` 工具产生 `agent.tool_use`，等待 `user.tool_confirmation`。使用 `type: custom` 声明的工具产生 `agent.custom_tool_use`，由客户端执行并提交 `user.custom_tool_result`。两类回复均通过 `data.event_id` 指定请求，不传 `session_thread_id`，同一调用以首条有效回复为准。 - **等待中的线程**：`requires_action` 和 `stop_reason.event_ids` 标识待返回的确认与自定义工具结果。每个线程收到全部待返回回复后恢复执行，会话级列表汇总所有等待线程。子线程状态、请求和回复出现在会话事件流中，由顶层 `session_thread_id` 标识所属线程。 ### 2026-10-09 - MCP 工具在工具集与单个工具均未设置 `load_mode` 时改为按需加载：模型先获得名称，需要时再加载 schema。需要保留原加载行为时，设置 `load_mode: eager`，让 schema 随每次请求发送；不支持按需加载的模型仍使用 eager 加载。 - `default_toolset_20260901` 中的 `search_image_by_text` 与 `search_image_by_image` 采用同一默认规则，其他内置工具仍为 `eager`。 ### 2026-09-24 - `project` 插件引用接受 `version: "latest"`，每次唤醒时解析为采用版本。省略版本仍在写入时固定为最新发布版本。`official` 引用必须省略版本，任何显式值都返回 400 `invalid_parameter_error`。 ### 2026-09-23 - **提示词校验**：创建和更新会话时，无效的 `agent_overrides.system` 模板返回 400 `invalid_parameter_error`。 - **执行事件**：新增 `agent.model_started` 和 `agent.tool_started` 事件，标记模型请求与工具执行的开始。流式调用在各自首个片段产生 `agent.thinking_started` 和 `agent.message_started`，非流式调用不产生这两个事件。可用 `agent.model_started` 到首个 `agent.delta` 计算 TTFT。 - **配置通知**：并发更新按提交顺序产生 `session.updated`，该事件不标识运行中的执行何时采用新配置。 ### 2026-09-21 #### 项目插件 - **项目插件**：`POST /v1/plugins` 和 `POST /v1/plugins/{id}/versions` 发布不超过 64 MiB 的 `.zip` 包，返回 201 与插件、版本和校验结果，两者均接受 `Idempotency-Key`。`POST /v1/plugins/validate` 只校验而不发布；不可发布的包返回 200 和 `ok: false` 的校验结果。 - **插件版本与归档**：`GET /v1/plugins/{id}/versions` 按语义版本从新到旧列出，`GET /v1/plugins/{id}/versions/{version}/content` 下载 `application/zip`。`POST /v1/plugins/{id}/archive` 返回 204，插件退出读取 API，项目内名称释放，已有精确版本引用继续有效。 - **插件选择**：`GET /v1/plugins` 接受 `scope` 为 `official` 或 `project`，省略返回两者，`org` 和 `user` 返回 400 `invalid_parameter_error`。`Plugin` 新增 `scope`、`status` 和 `latest_version`，`version` 仍表示配置写入时固定的版本。 - **会话插件**：创建和更新接受 `agent_overrides.plugins`，以与 `skills` 相同的三态语义替换冻结智能体的插件集合。`official` 条目省略 `version`，`project` 条目可以指定已发布版本。 #### OAuth 路由 - `MCPOAuthCredential` 和 `CreateVaultOAuthSession` 接受 `egress_environment_id`，发现、动态客户端注册、令牌交换与后台刷新均经过该环境的代理。空字符串清除绑定；新建时省略表示不绑定，更新时省略保留已有绑定。 ### 2026-09-20 - 插件和技能响应新增用于展示的可选 `categories`，未分类时省略，声明的分类包括 `finance`。分类不改变智能体配置。`GET /v1/plugins` 和 `GET /v1/skills` 接受 `category` 过滤列表。 ### 2026-09-19 - 智能体与会话的 `model.reasoning_effort` 接受 `max`，它仍是所选模型可能忽略的提示。 ### 2026-09-17 #### 会话输入与配置 - **输入容量**：会话已有 50 条待处理输入时，新输入返回 400 `failed_precondition_error`。消费或撤回释放容量，Interrupt 和 Continue 仍可使用。 - **会话覆盖**：`agent_overrides` 在 `mcp_servers`、`skills` 之外新增 `tools`、`model` 和 `system`。`roster` 只能在创建时覆盖，`PATCH` 携带它返回 400 `invalid_parameter_error`。 - **技能版本**：省略版本在写入时冻结为当前版本，`"latest"` 在每次唤醒时解析，精确版本经过校验后固定使用。同一 `skill_id` 混用 `"latest"` 和精确版本返回 400 `invalid_parameter_error`。 - **更新事件**：`session.updated` 仅在实际变化时产生，只携带变更字段：生效智能体快照与覆盖文档，或 `title`。清空全部覆盖产生空 `agent_overrides` 对象，客户端可安全忽略不识别的事件。 #### 触发器投递与暂停 - **复用会话**：定时和手动 `reuse_session` 运行跳过上次因执行错误停止的空闲会话（`session_failed`）和已满队列（`session_queue_full`）。同一会话连续 3 次因这两类原因跳过才暂停触发器，其他结果重置计数，已有消息和会话自身重试不受影响。 - **触发器暂停**：计划运行自动暂停活跃触发器时发送 `trigger.paused` webhook。通过 `data.id` 查询触发器的 `paused_reason`，普通跳过和手动操作不发送该 webhook。 #### 契约修正与说明 - **触发器错误**：`TriggerRun.error` 和 `PausedReason.error` 使用 `TriggerError`，其仅供展示的 `type` 为开放字符串，包括 `fire_failed`、`session_failed` 和 `overlap_in_flight`。本次修正 schema 复用 `ErrorType` 的问题，线上负载不变。 - **补充既有行为**：中断保留待处理输入；触发器更新重新校验未修改的 `initial_events`；未配置子智能体名单的会话不提供编排工具；重复内置工具集只使用首份声明，不合并配置。请求与响应不变。 ### 2026-09-15 - **未知 JSON 字段**：未声明成员现在返回 400 `invalid_parameter_error`，路径如 `body.unknown_key`，此前会被忽略。调用方应移除请求中的额外成员。 - **时间过滤**：智能体和会话列表接受 `created_at_gt`、`created_at_gte`、`created_at_lt`、`created_at_lte` 及对应 `updated_at_*` 参数。`gt`、`lt` 不含边界，`gte`、`lte` 包含边界。 - **契约声明**：OpenAPI 从 3.1.0 升级为 3.2.0；`POST /v1/files` 和 `POST /v1/skills` 的 multipart 文件部分采用无类型 schema 与通配编码的标准声明；事件流通过 `itemSchema` 声明各事件的 `event` 和 `data`；创建操作共用一份 `Idempotency-Key` 参数。线上格式与请求处理行为不变。 ### 2026-09-14 - 非 nullable 的可选请求字段显式传 `null` 现在返回 400 `invalid_parameter_error`，路径如 `body.name` 或 `body.description`，此前会被视为省略。省略字段表示不修改，清空时使用该字段说明中约定的空值。 ### 2026-09-13 - 请求校验现在执行 query、path、header 和 JSON 输入声明的类型、必填、范围、模式、枚举与组合约束。违例返回 400 `invalid_parameter_error`，校验路径带位置前缀与数组下标，如 `body.mcp_servers[2].name`、`query.page_size`。此前部分违例被接受，或在后续校验中使用较短路径与不同消息。调用方应按声明约束检查请求，并使用 `error.type` 与 `param` 判断错误，不匹配消息措辞。 - 未声明的 `Content-Type` 现在返回 400 `invalid_request_error`，即使请求体可以解析。JSON 操作使用 `application/json`，上传使用 `multipart/form-data`。 ### 2026-09-10 2026-09-09 预告的持久中断行为现已生效。 - **中断**：空闲会话现在接受中断，返回 202 和 `control_epoch`，而非 400。会话与活跃线程异步停止，响应与 `user.interrupt` 确认均不代表完成，需通过获取会话接口核对。可选令牌为 `data.expected_control_epoch`，过期值返回 409 `conflict_error`；会话仍处于中断状态时，重复中断不推进控制版本。 - **继续**：`POST /v1/sessions/{id}/continue` 返回 `control_epoch`，未中断会话保持不变，正在停止或已终止的会话返回 409 `conflict_error`。请求被接受不代表启动完成，需核对返回控制版本上的 `continue_pending`。 - **排队输入**：停止后发送的新输入在收尾完成后恢复执行，保留输入本身不会恢复会话，恢复后保持队列顺序。 - **归档**：运行中的子线程可以归档并取消，会话停止期间也允许操作。父会话未终止时，重复归档子线程返回 204。归档会话在停止期间返回 409 `conflict_error`，运行期间仍返回 400。 ### 2026-09-09 本日公告持久中断契约，执行行为于 2026-09-10 生效。停止完成与恢复规则见该日记录。 - **控制状态**：线程新增 `interrupted`、`control_epoch`；会话新增 `stopping`、`interrupted`、`control_epoch`、`continue_pending`；事件可含 `epoch` 与 `user.interrupt` 确认。 - **生命周期操作**：契约新增无需请求体的 `POST /v1/sessions/{id}/continue`、空闲会话中断，以及停止后新输入恢复执行。可选的预期控制版本在过期时返回 409 `conflict_error`，省略则针对当前代次。子线程归档取消活跃执行；仍有生命周期任务或活跃线程时，删除会话返回 409 `conflict_error`。 - **触发器输入**：`initial_events` 和待处理事件接受可排队用户消息，不接受此 beta 中的中断命令。`reuse_session` 触发器会恢复已停止的会话。 ### 2026-09-07 - **字段错误**：JSON 类型与校验失败使用 `invalid_parameter_error` 和字段路径，union 错误定位到 union 本身；请求级错误使用不带 `param` 的 `invalid_request_error`。本次修正此前分类错误或路径不完整的字段错误，缺少 `user.message.data` 和低于下限的 `activity.min_changed_sessions` 现在会被拒绝。 - **不透明 ID**：资源 ID 不再声明 `pattern` 约束。调用方应移除基于旧模式的校验，其范围未覆盖所有已签发 ID。 - **MCP 错误**：`SessionErrorType` 新增 `mcp_connection_failed` 和 `mcp_authentication_failed`，用于初始连接或执行中途失败。凭据自动刷新并重试一次仍被拒绝时报告鉴权失败，其他刷新失败不作为会话错误。`SessionErrorPayload.mcp_server_name` 标识受影响的服务器，其他类型与旧事件不含该字段，应据此定位而不解析消息。 - **官方环境**：`GET /v1/environments` 新增 `official_only`，默认 false。 ### 2026-09-06 - `listTriggers` 接受 `agent_id`，按所属智能体过滤。 ### 2026-09-05 - `listMemoryStores` 和 `listMemories` 从按创建时间升序改为最新在前。依赖旧顺序的客户端需要调整处理逻辑。 - `GET /v1/agents` 新增 `official_only`，默认 false。 ### 2026-09-04 - **仅更新契约声明**：各操作声明可选的 `kimi-api-version` 请求头，线上仍要求 `/v1/files*` 之外携带，文件端点省略时采用兼容格式。事件流声明已有的 `Cache-Control: no-cache`、`X-Accel-Buffering: no` 响应头；共享 429 响应声明已有的 `Retry-After`，仅用于 `rate_limit_reached_error`。请求处理行为不变。 ### 2026-09-03 - **batch 文件**：向会话挂载 `batch` 文件返回 400 `failed_precondition_error`，而非 404 `resource_not_found_error`，仍不支持挂载。 - **MCP 请求头**：智能体和会话的 `McpServer` 声明接受只写的 `headers`，用于非敏感连接请求头。更新时，省略或空请求头保留身份未变的服务器（name、type、URL）的原值；非空整体替换，空字符串值删除键，仅大小写不同的重名请求头会被拒绝。 - **环境代理**：`EnvironmentProxy.route_all` 将全部出站主机经代理转发，并允许空 `hosts` 列表。平台内部端点绕过代理；`limited` 下主机白名单不生效，可达性由代理决定。 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: 管理执行环境及其配置。 - name: 凭据库 description: 管理凭据库、凭据和 OAuth 会话。 - name: 插件 description: 列出并查看可用插件。 - name: 记忆库 description: 管理记忆库、文件、版本和梦境策略。 - name: 触发器 description: 创建、管理和运行 Trigger。 paths: /v1/plugins/{id}/versions/{version}/content: get: tags: - 插件 summary: 获取插件版本内容 description: >- 下载项目自有插件指定确切发布版本的插件包归档。响应始终为 `application/zip`，字节与提交时的归档一致。`official` 插件不提供插件包下载，返回 400 `failed_precondition_error`。已归档的插件返回 404。 operationId: getPluginVersionContent parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string - name: version in: path required: true description: 确切的已发布语义版本，例如 `"1.0.0"`。 schema: type: string responses: '200': description: 存储的插件包归档字节（`application/zip`）。 content: application/zip: schema: contentMediaType: application/zip '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' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: >- 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' components: parameters: APIVersionHeader: name: kimi-api-version in: header required: false description: >- 本次请求使用的 API 版本，格式为 `YYYY-MM-DD`。发送 `2026-09-01-beta` 即使用本文档所述版本。`/v1/files*` 之外必传：未携带请求头将被拒绝并返回 400 `invalid_request_error`；在 `/v1/files*` 上缺省时选择兼容行为。所有端点对未知取值均返回 400 `invalid_request_error`。 schema: $ref: '#/components/schemas/APIVersion' schemas: BadRequestErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' UnauthorizedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' NotFoundErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' TooManyRequestsErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' APIError: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 错误详情。 APIVersion: type: string enum: - 2026-09-01-beta description: 平台当前支持的 API 版本。新的日期版本发布时加入；版本在公告的 Sunset 日期后移除。 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 版本共用的机器可读错误详情。 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 ````