# 概览
Praxis 是智能体云平台。API 按服务组织：智能体、模型、沙箱、搜索、自动化，各在自己的前缀下。请求与响应用 JSON，流式响应用 SSE，使用标准的 HTTP 动词与状态码。所有前缀共用一个地址和一个 Key。
## 基础地址 [#基础地址]
```
https://api.deepraxis.com
```
## 客户端库 [#客户端库]
使用服务 API 页列出的客户端库。兼容接口使用对应协议的官方 SDK；自动化提供 TypeScript SDK，本地安装方式见[自动化 API](/docs/api/native/automation)。
| 服务 | 前缀 | API 页 |
| --- | ------------- | --------------------------------------------- |
| 智能体 | `/agent` | [Agent API](/docs/api/native/agent) |
| 模型 | `/model` | [Model API](/docs/api/native/model) |
| 沙箱 | `/sandbox` | [Sandbox API](/docs/api/native/sandbox) |
| 搜索 | `/search` | [Search API](/docs/api/native/search) |
| 自动化 | `/automation` | [Automation API](/docs/api/native/automation) |
## 兼容接口 [#兼容接口]
已经在用 OpenAI、Anthropic、Google、E2B 或 Tavily 的代码，不需要改成 Praxis 的接口：平台提供与这些厂商官方 API 一致的兼容前缀，只改地址就能用。
| 厂商 | 前缀 | API 页 |
| --------- | ------------ | ---------------------------------------------- |
| OpenAI | `/openai` | [OpenAI 兼容](/docs/api/compatible/openai) |
| Anthropic | `/anthropic` | [Anthropic 兼容](/docs/api/compatible/anthropic) |
| Google | `/google` | [Google 兼容](/docs/api/compatible/google) |
| E2B | `/e2b` | [E2B 兼容](/docs/api/compatible/e2b) |
| Tavily | `/tavily` | [Tavily 兼容](/docs/api/compatible/tavily) |
## 一个 Key [#一个-key]
所有前缀共用在控制台创建的 API Key，随请求放在 `Authorization` 头里。详见[鉴权](/docs/api/authentication)。
## 全局约定 [#全局约定]
* 错误用标准 HTTP 状态码表达类别，错误体按前缀的格式给出原因。详见[错误](/docs/api/errors)。
* 超出额度返回 `429`，响应头告诉你何时可以重试。详见[限流](/docs/api/rate-limits)。
* 版本号写在地址里，弃用提前 90 天以标准头通知。详见[版本](/docs/api/versioning)。
* 关于 API 本身的信息（OpenAPI 描述、健康状态）在 `/meta` 前缀下。
## 第一个请求 [#第一个请求]
```bash
curl https://api.deepraxis.com/model/v1/chat/completions \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}'
```
# 鉴权
所有接口用同一种凭证：在控制台创建的 API Key，随请求放在 `Authorization` 头里。没有别的鉴权方式，也没有按接口不同的规则。
## 一个头 [#一个头]
```
Authorization: Bearer {key}
```
| 段 | 含义 | 例子 |
| -------- | ---------------------------- | ----------------- |
| `Bearer` | 固定字样 | `Bearer` |
| `{key}` | 你的 API Key，以 `sk-praxis-` 开头 | `sk-praxis-a1b2…` |
一个 Key 通所有前缀下的接口。Key 在[控制台 → API Key](/docs/cloud/account/api-keys) 创建、轮换和吊销；吊销立即生效。
## 各家 SDK 把 Key 放在哪 [#各家-sdk-把-key-放在哪]
你不需要自己拼这个头——官方 SDK 会放；我们同时接受各家 SDK 默认使用的头名。
| SDK | 你传什么 | 实际发出的头 |
| ----------------- | -------- | ------------------------- |
| OpenAI SDK | `apiKey` | `Authorization: Bearer …` |
| Anthropic SDK | `apiKey` | `X-API-Key: …` |
| Google GenAI SDK | `apiKey` | `x-goog-api-key: …` |
| E2B SDK | `apiKey` | `X-API-Key: …` |
| Tavily SDK / HTTP | `apiKey` | `Authorization: Bearer …` |
## 试一条 [#试一条]
```bash
curl https://api.deepraxis.com/model/v1/models \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
## 鉴权失败长什么样 [#鉴权失败长什么样]
Key 缺失、无效或已吊销，返回 `401`，错误体按该前缀的格式（见[错误](/docs/api/errors)）。收到 `401` 不要重试——换对 Key 再发。
## 保管 [#保管]
* 只在服务端使用；不要放进浏览器、移动端或公开仓库。
* 用环境变量（示例里的 `PRAXIS_API_KEY`），不要写进代码。
* 怀疑泄露时在控制台吊销并新建，旧 Key 立即失效。
# 错误
出错时，HTTP 状态码告诉你错误属于哪一类；错误体按该前缀的格式给出具体原因；每个错误响应还带四个 `x-praxis-problem-*` 头和一个 `x-praxis-recovery-action`（限流错误再多带一个 `x-praxis-problem-scope`，见[限流](/docs/api/rate-limits)），不论错误体长什么样，重试逻辑只看头就够。
## 状态码 [#状态码]
| 状态码 | 含义 | 你该做什么 |
| ----- | -------------- | ------------------------------ |
| `400` | 请求字段或格式不合法 | 修正参数，不要原样重试 |
| `401` | 缺少或无效的凭证 | 检查 API Key |
| `402` | 余额或付费额度不足 | 补充余额或联系账户管理员 |
| `403` | 无权访问该资源或操作 | 核对 Key 权限与资源归属；必要时联系支持 |
| `404` | 资源、模型或路径不存在 | 检查 ID、模型名和路径 |
| `408` | 请求超时 | 检查网络后重试；写操作先确认是否已完成 |
| `409` | 资源状态或并发修改冲突 | 重新读取状态，再调整请求 |
| `413` | 请求体或文件超过大小限制 | 减小内容或改用端点支持的 URL 输入 |
| `422` | 请求内容无法处理 | 根据错误详情修正参数或输入 |
| `429` | 请求速率、并发或模型额度超限 | 按 retry-after 等待；并发超限时等待在途请求结束 |
| `500` | 平台内部错误 | 稍后重试；持续出现请附 X-Request-Id 联系支持 |
| `501` | 功能尚未支持 | 换用已支持的端点，不要重试 |
| `502` | 上游调用失败或返回无效响应 | 退避重试，持续失败时换模型或联系支持 |
| `503` | 服务或可用线路暂不可用 | 退避重试，或选择其它模型 |
| `504` | 上游响应超时 | 退避重试；写操作先确认结果，避免重复创建 |
## 错误码 [#错误码]
以下是常见的机器可读错误码，不是所有端点的封闭枚举。兼容接口的错误体可能使用协议自己的 code/type；跨协议判断可读取 `x-praxis-problem-code`，其值可能与错误体 code 不同。大小写按返回值区分。
| code | 什么时候出现、该怎么办 |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUTHENTICATION_ERROR` | Key 缺失或无效；检查并更换凭证。 |
| `VALIDATION_ERROR` | 参数不符合格式、类型或范围要求；按详情改参数。 |
| `INPUT_NOT_REPRESENTABLE` | 所选模型或协议无法表达输入选项；删除该选项或换模型。 |
| `NOT_FOUND` | 资源不存在或对当前账户不可见；核对 ID 与账户。 |
| `MODEL_NOT_FOUND` | 模型不存在或不可见；从模型列表选取可用名称。 |
| `MODEL_PROTOCOL_NOT_OFFERED` | 模型不提供所请求的协议；换用其支持的端点或模型。 |
| `MODEL_PROTOCOL_LINE_UNAVAILABLE` | 支持该协议的合格线路暂不可用；退避重试或换模型。 |
| `GENERATION_NOT_FOUND` | 生成记录不存在或不属于当前账户；核对响应头中的生成 ID 与 Key。 |
| `RATE_LIMITED` | 超过速率或并发限额；按 retry-after 等待并降低速率或并发。 |
| `UPSTREAM_ERROR` | 上游调用失败或响应不合法；按 retryable 退避重试，持续失败时换模型或联系支持。 |
| `PROVIDER_SELECTION_NOT_ALLOWED` | 指定供应商 order/only 时没有携带 BYOK；移除供应商选择或提供自己的上游 Key。 |
| `not_implemented` | 该端点或能力未实现；换用已支持的能力，不要原样重试。 |
| `model_protocol_not_offered` | HTTP 404；模型未声明所请求的协议。查询 `GET /model/v1/models` 的 `supported_apis`，改用相应入口，例如声明 Google 协议的模型使用 `/google/v1beta/models/{model}:generateContent`；不要只换前缀而保留另一协议的请求体。 |
| `provider_unavailable` | HTTP 502；本次请求的可用线路全部失败。退避重试，持续失败时换模型，并附 `X-Request-Id` 联系支持。 |
| `thinking_disable_unsupported` | HTTP 400；模型不能关闭思考，例如对 `glm-5.3` 设置 `reasoning_effort="none"`。移除关闭设置或选择支持的思考等级；需要关闭思考时换模型。 |
| `insufficient_quota` / `INSUFFICIENT_BALANCE` | HTTP 402；余额不足，错误体或响应头的代码因入口而异。充值或联系账户管理员后再重试，不要立即循环重试。 |
| `validation_error`（`response_format`） | HTTP 400；例如 `Model "deepseek-flash" does not support json_schema on this API.`。换用在该入口支持 `json_schema` 的模型；若只需要合法 JSON，可改用 `json_object`，但它不保证 schema 约束。 |
| `validation_error`（参数被点名） | HTTP 400；设置 `provider.require_parameters=true` 时，所选模型仍可能无法支持请求参数，例如 `param: "logprobs"`、`does not support the requested logprobs value`。按 `param` 和消息调整参数或换模型；不要只关闭检查后假定参数已生效。 |
## 错误体 [#错误体]
错误体的格式跟着地址第一段走，和成功响应一致——你的 SDK 不需要为错误特殊处理。
**厂商前缀**（`/openai` `/anthropic` `/google` `/e2b` `/tavily`）：和该前缀对应的官方 API 错误体一模一样。
```json
// /openai
{ "error": { "code": 401, "message": "Invalid API key." } }
```
```json
// /anthropic
{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid API key." } }
```
**Praxis 前缀**（`/agent` `/model` `/sandbox` `/search` `/meta`）：标准的 Problem Details（RFC 9457），`Content-Type: application/problem+json`。
```json
{
"type": "https://deepraxis.ai/problems/authentication_error",
"title": "authentication_error",
"status": 401,
"detail": "Invalid API key.",
"instance": "problem_eqfnxu",
"code": "AUTHENTICATION_ERROR",
"retryable": false
}
```
| 字段 | 含义 |
| ------------------ | ------------------ |
| `type` | 错误类型的 URL，稳定，可用来分支 |
| `title` / `detail` | 给人读的摘要与具体原因 |
| `status` | 同 HTTP 状态码 |
| `instance` | 本次错误的 ID，联系支持时附上 |
| `code` | 机器可读的错误码 |
| `retryable` | 原样重试是否可能成功 |
## 错误响应头（五个通用头 + 一个限流头） [#错误响应头五个通用头--一个限流头]
五个通用头与错误体格式无关；第六个 scope 头仅适用于限流错误：
| 头 | 含义 | 例子 |
| ---------------------------- | --------------------------------------------------------------------- | ------------------------ |
| `x-praxis-problem-code` | 跨协议分类码；可能与错误体的 `code` 不同 | `AUTHENTICATION_ERROR` |
| `x-praxis-problem-kind` | 错误大类——出了什么事 | `authentication_failure` |
| `x-praxis-problem-origin` | 错误归谁——谁能解决它：`user`（你的请求或凭证）、`platform`（我们）、`upstream_provider`（上游厂商）等 | `unknown` |
| `x-praxis-problem-retryable` | 原样重试是否可能成功 | `false` |
| `x-praxis-problem-scope` | 仅限流错误：触发的保护层——`platform` 平台层、`model` 模型层 | `platform` |
| `x-praxis-recovery-action` | 建议的处理动作 | `relogin` |
## 重试 [#重试]
* `retryable` 为 `true`（或状态码 `429` `502` `503`）：指数退避重试；`429` 优先按 `retry-after`。
* 其它一律不要原样重试——先改请求或 Key。
# 限流
Praxis 的限流分两层：**平台层**按你的 Key 限每秒请求数和同时进行的请求数；**模型层**按模型限每分钟请求数（RPM）和每分钟 token 数（TPM）。每个响应——不论成功还是 `429`——都带三个 `x-ratelimit-*` 头，写明当前额度和重置时间，你不需要猜，也不需要为读额度多发请求。
## 两层限额 [#两层限额]
| 层 | 按什么计 | 限什么 | 超出的表现 |
| --- | ------------------- | --------------------------------- | --------------------------- |
| 平台层 | 你的 Key（没带凭证时按来源 IP） | 每秒请求数、同时进行的请求数 | `429` + `retry-after`，等待后重试 |
| 模型层 | 模型 × 租户 | 每分钟请求数（RPM）、每分钟 token 数（TPM）、月度预算 | `429`，见下文模型层 |
两层的 `429` 都带同样的三个限流头；是哪一层触发的，看错误体的说明（[错误](/docs/api/errors)）。
## 平台层：每秒请求数与并发数 [#平台层每秒请求数与并发数]
默认每个 API Key **每秒最多 5 个请求，同时最多 4 个在途请求**。流式请求在流结束前占用并发槽位。超过任一默认限额返回 `429`，响应带 `ratelimit-limit`、`ratelimit-remaining`、`ratelimit-reset` 和 `retry-after`；并发超限须等已有请求结束。
实际限额可能因账户而异；以响应头和并发错误详情为准。
### 三个响应头 [#三个响应头]
```http
x-ratelimit-limit-requests: 5
x-ratelimit-remaining-requests: 4
x-ratelimit-reset-requests: 850ms
```
| 头 | 含义 |
| -------------------------------- | ------------------------------------- |
| `x-ratelimit-limit-requests` | 该凭证每秒的请求上限 |
| `x-ratelimit-remaining-requests` | 本秒还剩多少个请求 |
| `x-ratelimit-reset-requests` | 距离额度重置的时间：不满一秒写作 `850ms`，一秒及以上写作 `1s` |
同样的三个数也以 IETF 标准名 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`（整数秒）同时给出。以上 5 次/秒、4 个并发为默认限额；配置覆盖后的请求速率以响应头显示为准。
### 超出每秒上限 [#超出每秒上限]
一秒内的第 N+1 个请求（N 为该 Key 的每秒上限）返回 `429`，并带 `retry-after`（整数秒，通常是 `1`）。**被拒绝的请求不消耗额度**：`x-ratelimit-remaining-requests` 保持 `0`，等窗口重置即可恢复。
### 超出并发上限 [#超出并发上限]
同时进行的请求（包括尚未结束的流式响应——流结束前一直占坑）超过该 Key 的并发上限时，多出的请求返回 `429`，`retry-after` 为 `1`。这种情况下**仅等待秒级窗口重置不会释放并发槽位**：须等一个进行中的请求结束。是并发还是每秒触发的，错误说明里写得很清楚（"Concurrent request limit …" / "Requests per second limit …"）。
### 错误体 [#错误体]
错误体跟着地址第一段走（见[错误](/docs/api/errors)）。`/model/v1/chat/completions` 等原生端点是 Problem Details：
```json
{
"type": "https://deepraxis.ai/problems/rate_limit",
"title": "rate_limited",
"status": 429,
"detail": "Requests per second limit of 5 exceeded for this credential. Retry after the listed wait.",
"instance": "problem_eqfnxu",
"kind": "rate_limit",
"scope": "platform",
"retryable": true
}
```
`scope: "platform"` 表示是平台层触发的（模型层限额的错误不带此字段或为 `model`）。`/openai/v1/chat/completions` 等厂商前缀按该家的错误格式，例如 OpenAI 兼容端点：
```json
{ "error": { "code": 429, "type": "rate_limit_error", "message": "Requests per second limit of 5 exceeded for this credential. Retry after the listed wait." } }
```
### 没带凭证的请求 [#没带凭证的请求]
公开端点（如 `GET /model/v1/models`）允许不带 Key 调用，这时按**来源 IP** 计入一个较小的匿名额度，响应头同样给出。带了 Key 就按 Key 计，与 IP 无关。
`GET /meta/v1/health` 不限流，探活监控可以任意频率调用。
## 模型层：每分钟请求数与 token 数 [#模型层每分钟请求数与-token-数]
限额维度是**模型 × 租户 × 分钟**，不是 API Key：
* 每个模型在模型元数据里配置自己的 **RPM**（每分钟请求数）与 **TPM**（每分钟 token 数）；未配置或为 `0` 表示不限制。
* 命中任一限额返回 `429`，`type` 为 `rate_limit_error`，`Retry-After: 60`，`problem.details.rateLimit` 给出当前值与限额。
* **BYOK 调用自带供应商凭证，不占平台模型限额。**
* 上游供应商限流由平台自动 failover 到其他供应商；全部供应商不可用时按返回的 `429` 处理。
模型另有**月度预算**：按模型当月累计收入计，超出返回 `429`，`type` 为 `budget_error`（`QUOTA_EXHAUSTED`），无 `Retry-After`——等待无效，需要提升该模型的预算。
错误体与状态码见[错误](/docs/api/errors)；账号额度见[配额与限流](/docs/cloud/account/quotas)。
# 版本
版本号写在地址里，紧跟第一段；每个前缀各自计版本，没有全站统一的版本号。
## 地址里的版本段 [#地址里的版本段]
```
https://api.deepraxis.com/{protocol}/{version}/…
```
| 前缀 | 版本段 | 由谁决定 |
| ---------------------------------------------- | -------- | ------ |
| `/openai` `/anthropic` | `v1` | 跟随厂商 |
| `/google` | `v1beta` | 跟随厂商 |
| `/e2b` `/tavily` | 无版本段 | 跟随厂商 |
| `/agent` `/model` `/sandbox` `/search` `/meta` | `v1` | Praxis |
厂商前缀下，版本相关的头（如 Anthropic 的 `anthropic-version`）原样透传给厂商，行为与官方一致。
## 什么算破坏性变更 [#什么算破坏性变更]
删字段、改字段类型或含义、改默认值、收紧校验、改错误码含义。加字段、加端点、放宽校验不算。
## Beta 与正式 [#beta-与正式]
* **Beta**：端点页标有「Beta」。可能随时改动，不做兼容承诺；适合试用，不建议放进生产。
* **正式**：破坏性变更只会以新版本段发布（如 `/model/v2/…`），旧版本继续可用。
## 弃用怎么通知 [#弃用怎么通知]
旧版本或端点弃用时：
1. 更新日志公告，并给出替代方案；
2. 该端点的响应带两个标准头：`Deprecation`（RFC 9745，何时弃用）与 `Sunset`（RFC 8594，何时下线），`Link` 头指向迁移说明；
3. 从公告到下线至少 **90 天**；下线后返回 `404`。
```
Deprecation: @1767225600
Sunset: Sat, 04 Apr 2026 00:00:00 GMT
Link: ; rel="deprecation"
```
# OpenAI 兼容接口
## 基础地址 [#基础地址]
## 接入 [#接入]
## 端点 [#端点]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
| POST | [`/v1/chat/completions`](/docs/api/compatible/openai/createChatCompletion) | 对话 | ● 支持 |
| POST | [`/v1/responses`](/docs/api/compatible/openai/createResponse) | 生成响应 | ● 支持 |
| GET | [`/v1/responses/{response_id}`](/docs/api/compatible/openai/retrieveResponse) | 读取响应 | ● 支持 |
| DELETE | [`/v1/responses/{response_id}`](/docs/api/compatible/openai/deleteResponse) | 删除响应 | ● 支持 |
| POST | [`/v1/responses/{response_id}/cancel`](/docs/api/compatible/openai/cancelResponse) | 取消响应 | ◐ 部分支持 |
| GET | [`/v1/responses/{response_id}/input_items`](/docs/api/compatible/openai/listResponseInputItems) | 列出响应输入项 | ● 支持 |
| POST | [`/v1/responses/compact`](/docs/api/compatible/openai/compactResponse) | 压缩响应 | ○ 未支持 |
| POST | [`/v1/responses/input_tokens`](/docs/api/compatible/openai/countResponseInputTokens) | 统计输入 token | ○ 未支持 |
| POST | [`/v1/conversations`](/docs/api/compatible/openai/createConversation) | 创建会话 | ● 支持 |
| GET | [`/v1/conversations/{conversation_id}`](/docs/api/compatible/openai/retrieveConversation) | 读取会话 | ● 支持 |
| POST | [`/v1/conversations/{conversation_id}`](/docs/api/compatible/openai/updateConversation) | 更新会话 | ● 支持 |
| DELETE | [`/v1/conversations/{conversation_id}`](/docs/api/compatible/openai/deleteConversation) | 删除会话 | ● 支持 |
| POST | [`/v1/conversations/{conversation_id}/items`](/docs/api/compatible/openai/createConversationItems) | 创建会话条目 | ● 支持 |
| GET | [`/v1/conversations/{conversation_id}/items`](/docs/api/compatible/openai/listConversationItems) | 列出会话条目 | ● 支持 |
| GET | [`/v1/conversations/{conversation_id}/items/{item_id}`](/docs/api/compatible/openai/retrieveConversationItem) | 读取会话条目 | ● 支持 |
| DELETE | [`/v1/conversations/{conversation_id}/items/{item_id}`](/docs/api/compatible/openai/deleteConversationItem) | 删除会话条目 | ● 支持 |
| POST | [`/v1/images/generations`](/docs/api/compatible/openai/createImage) | 生成图像 | ● 支持 |
| GET | [`/v1/models`](/docs/api/compatible/openai/listModels) | 列出模型 | ● 支持 |
| GET | [`/v1/models/{model}`](/docs/api/compatible/openai/retrieveModel) | 读取模型 | ● 支持 |
| POST | [`/v1/embeddings`](/docs/api/compatible/openai/createEmbedding) | 文本向量 | ● 支持 |
| POST | [`/v1/videos`](/docs/api/compatible/openai/createVideo) | 创建视频 | ● 支持 |
| GET | [`/v1/videos`](/docs/api/compatible/openai/listVideos) | 列出视频 | ● 支持 |
| GET | [`/v1/videos/{video_id}`](/docs/api/compatible/openai/retrieveVideo) | 读取视频 | ● 支持 |
| GET | [`/v1/videos/{video_id}/content`](/docs/api/compatible/openai/downloadVideoContent) | 下载视频内容 | ● 支持 |
| DELETE | [`/v1/videos/{video_id}`](/docs/api/compatible/openai/deleteVideo) | 删除视频 | ● 支持 |
| POST | [`/v1/videos/{video_id}/remix`](/docs/api/compatible/openai/remixVideo) | 混剪视频 | ○ 未支持 |
| POST | [`/v1/audio/transcriptions`](/docs/api/compatible/openai/openaiAudioTranscriptionsCreate) | 转写音频 | ● 支持 |
| POST | [`/v1/files`](/docs/api/compatible/openai/createFile) | 上传文件 | ◐ 部分支持 |
| GET | [`/v1/files`](/docs/api/compatible/openai/listFiles) | 列出文件 | ● 支持 |
| GET | [`/v1/files/{file_id}`](/docs/api/compatible/openai/retrieveFile) | 检索文件 | ● 支持 |
| DELETE | [`/v1/files/{file_id}`](/docs/api/compatible/openai/deleteFile) | 删除文件 | ● 支持 |
| GET | [`/v1/files/{file_id}/content`](/docs/api/compatible/openai/retrieveFileContent) | 检索文件内容 | ● 支持 |
| POST | `/v1/audio/speech` | 生成语音 | ● 支持 |
| POST | `/v1/images/edits` | 编辑图片 | ● 支持 |
[知识库（16 个操作）](/docs/api/compatible/openai/vector-stores)：创建知识库、添加文件、批量入库与搜索。
## 不支持的端点 [#不支持的端点]
以下端点在 /openai/v1 下未提供，调用返回 404。替代流程不等同于原端点。
| 端点 | 替代 |
| ------------------------ | ------------------------------------------------- |
| `/v1/moderations` | 无替代端点 |
| `/v1/batches` | 逐次调用所需模型端点 |
| `/v1/fine_tuning` | 使用模型目录中已有的模型 |
| `/v1/assistants` | 使用 Responses 与 Conversations 构建会话 |
| `/v1/completions` | 改用 chat/completions |
| `/v1/audio/translations` | 先用 audio/transcriptions 转写，再用 chat/completions 翻译 |
| `/v1/uploads` | 改用 files 上传文件 |
| `/v1/images/variations` | 使用 images/edits 提交图片与编辑提示词 |
## 与官方的差异 [#与官方的差异]
* 对话：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* 生成响应：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* 读取响应：按 ID 读取一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，读取会返回 404 response\_not\_found；超过保留期（默认 30 天）后读取也会返回同样的 404。
* 删除响应：按 ID 立即删除一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，删除会返回 404 response\_not\_found。
* 取消响应：仅对以 background:true 创建、且路由到具备后台生成能力的模型的响应可用：取消是 幂等的，重复调用返回同一个终态响应；我方的取消只能停止我方对上游流的继续读取， 不能保证已发往上游的算力停止计算，用量按实际收到的部分结算。对一个非后台 （同步）响应调用 cancel：如果这个响应 id 不存在（未持久化、已过期或 id 有误）， 返回 404 object\_not\_found；如果响应存在但其来源 provider 没有声明支持 cancel 操作（我们目前没有接入任何为同步响应声明该能力的上游），返回 400 native\_responses\_operation\_unsupported。这两种情况都不是尚未实现的 501 gate。
* 列出响应输入项：列出一条已保存响应的输入项。支持 limit（1–100，默认 20）、order（asc/desc， 默认 desc，与官方一致）与基于条目 id 的 after 游标分页；has\_more/first\_id/ last\_id 均与实际返回页一致，可据此翻页且不重不漏。每个条目都带服务端签发的 id（message 为 msg\_ 前缀，function\_call/function\_call\_output/reasoning 各自 对应前缀），本次上线前已保存、尚无服务端 id 的旧数据在读取时按确定性规则补 id，不做破坏性迁移，同一游标反复读取保持稳定。以 previous\_response\_id 续接 创建的响应，其输入项列出解析后的完整输入：前序响应链已有的输入与输出条目 再加本轮自己提交的输入；若该祖先响应在我方平台未保存（例如创建时 store 为 false）或已过期删除，则只列出本轮自己提交的输入。如果创建时 store 为 false，我们不会保存这次响应，列出会返回 404 response\_not\_found。
* 压缩响应：把响应的输入压缩成摘要，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
* 统计输入 token：只统计请求输入会消耗的 token 数、不生成内容，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
* 创建会话：创建一个会话，可选携带初始 items（一次最多 20 条）与 metadata。会话按租户分区，创建者是唯一能引用它的租户。
* 读取会话：按 ID 读取一个会话。不存在或属于其他租户都返回 404 conversation\_not\_found。
* 更新会话：更新一个会话的 metadata——整体替换，不与已有 metadata 合并。
* 删除会话：删除一个会话。删除后该会话与其 items 都不能再被引用（包括作为 Responses create 的 conversation 参数）。
* 创建会话条目：向一个会话追加 items（一次最多 20 条），返回刚追加的这些 items。
* 列出会话条目：按创建顺序列出会话的 items，支持 limit/after/order 分页参数。
* 读取会话条目：按 ID 读取会话里的单条 item。
* 删除会话条目：删除会话里的单条 item，返回该会话对象（不是被删除的 item）。
* 读取模型：返回与列表中同一条目相同的模型对象。只有声明了 OpenAI 协议的模型可见；模型 ID 可以带斜杠分隔的发布方前缀。不存在或没有声明 OpenAI 协议的模型返回 404。
* 文本向量：转发方式与对话（chat completions）一致，用量算在同一份计费里。 未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* 创建视频：异步生成视频：创建任务后轮询状态，完成后下载内容。按输出秒数计费，每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。请显式选择已注册的视频模型，例如 wan2.7-t2v。
* 列出视频：列出本账号的视频任务。limit 为 1 到 100，order 为 asc 或 desc，after 必须引用存在的任务。
* 读取视频：读取任务的当前状态和进度。status 为 queued 或 in\_progress 时继续轮询，failed 时查看 error，completed 后才能下载内容。任务不存在返回 404。
* 下载视频内容：任务 completed 后下载视频文件（video，MP4）或缩略图（thumbnail）；spritesheet 返回 400，index 只支持 0。任务不存在返回 404。
* 删除视频：删除任务及其生成的内容。任务不存在返回 404。
* 混剪视频：未支持，调用固定返回 400（invalid\_request\_error，消息为 Video remix is not supported）；不要重试。
* 转写音频：标准请求字段；不能表达的参数返回 input\_not\_representable。
* 上传文件：单文件最多 100 MB（104857600 字节）；按内容识别 PDF、Office、图片、音频、视频与 UTF-8 文本。purpose 支持 user\_data / assistants / vision；其他用途、空文件、不支持类型和超限均返回 400。不支持 Uploads 分片。只接受表单 file、purpose、expires\_after\[anchor]、expires\_after\[seconds]；其他表单字段或任何查询参数返回 400 invalid\_request\_error，消息为 "Unrecognized request argument supplied: \<字段>"，param 为该字段。
* 列出文件：只接受查询参数 after、order、limit、purpose；其他查询参数返回 400 invalid\_request\_error，消息为 "Unrecognized request argument supplied: \<参数>"，param 为该参数。
参数与字段的权威定义以 [OpenAI 官方文档](https://platform.openai.com/docs/api-reference)为准。
错误按 OpenAI 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
# 对话
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful chat completion response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| choices | array<object> | List of completion choices |
| choices[].finish_reason | string | null | |
| choices[].index | integer | Choice index |
| choices[].logprobs | object | null | Log probabilities for the completion |
| choices[].message | object | Assistant message for requests and responses |
| created | integer | Unix timestamp of creation |
| id | string | Unique completion identifier |
| model | string | Model used for completion |
| object | string | |
| openrouter_metadata | object | Routing report: what was requested, how the router chose, and what was attempted. |
| openrouter_metadata.attempt | integer | Number of the attempt that served the request, starting at 1. |
| openrouter_metadata.attempts | array<object> | Every attempt that was made, in order. |
| openrouter_metadata.endpoints | object | Which endpoints were available and which one was chosen. |
| openrouter_metadata.generation_time | integer | Milliseconds measured for the generation, from dispatching the upstream request until its response body ended. Divide the completion token count by this for throughput. Absent when no upstream request was dispatched. |
| openrouter_metadata.is_byok | boolean | Whether the request used a key supplied by the caller. |
| openrouter_metadata.params | object | Router parameters that applied to the request. |
| openrouter_metadata.pipeline | array<object> | Stages the request went through before and after the model call. |
| openrouter_metadata.region | string | null | Region that served the request; null when unknown. |
| openrouter_metadata.requested | string | The model or alias the request asked for. |
| openrouter_metadata.strategy | string | How the router picked the model or provider for this request. |
| openrouter_metadata.summary | string | One-line summary of the routing decision. |
| service_tier | string | null | The service tier used by the upstream provider for this request |
| system_fingerprint | string | null | System fingerprint |
| usage | object | Token usage statistics |
| usage.completion_tokens | integer | Number of tokens in the completion |
| usage.completion_tokens_details | object | null | Detailed completion token usage |
| usage.cost | number | null | Cost of the completion |
| usage.cost_details | object | null | Breakdown of upstream inference costs |
| usage.is_byok | boolean | Whether a request was made using a Bring Your Own Key configuration |
| usage.prompt_tokens | integer | Number of tokens in the prompt |
| usage.prompt_tokens_details | object | null | Detailed prompt token usage |
| usage.server_tool_use_details | object | null | Usage for server-side tool execution (e.g., web search) |
| usage.total_tokens | integer | Total number of tokens |
**text/event-stream — chunk / 事件对象**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | object | Streaming chat completion chunk |
| data.choices | array<object> | List of streaming chunk choices |
| data.created | integer | Unix timestamp of creation |
| data.error | object | Error information |
| data.id | string | Unique chunk identifier |
| data.model | string | Model used for completion |
| data.object | string | |
| data.openrouter_metadata | object | Routing report: what was requested, how the router chose, and what was attempted. |
| data.service_tier | string | null | The service tier used by the upstream provider for this request |
| data.system_fingerprint | string | System fingerprint |
| data.usage | object | Token usage statistics |
# 生成响应
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| background | boolean | null | Whether the response was started in background mode. |
| completed_at | integer | null | Unix time in seconds at which the response finished; null while it has not finished. |
| created_at | integer | Unix time in seconds at which the response was created. |
| error | object | null | Error information returned from the API |
| error.code | string | Machine-readable error code. |
| error.message | string | Human-readable error message. |
| frequency_penalty | number | null | The frequency penalty that applied to the request, if any. |
| id | string | Unique id of the response; use it as response_id to retrieve, cancel or delete it, or as previous_response_id to continue the conversation. |
| incomplete_details | object | null | Why the response stopped before finishing; null for complete responses. |
| incomplete_details.reason | string | Why the response is incomplete. |
| instructions | string | array<object> | null | Input of the request: a string or an array of input items. |
| max_output_tokens | integer | null | Upper bound on generated tokens that applied to the request; null when none was set. |
| max_tool_calls | integer | null | Upper bound on built-in tool calls that applied to the request; null when none was set. |
| metadata | object | null | Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed. |
| model | string | Model that produced the response. |
| object | string | Object type; always `response`. |
| output | array<object> | Items the model produced, in order: messages, reasoning, tool calls and tool results. |
| output[].content | array<object> | array | null | string | Content parts of the message: output text or refusal. / Reasoning text parts, when the provider returns them. / Text content of the fetched page. |
| output[].id | string | Id of the message item. / Id of the reasoning item. / Id of the function call item. / Id of the web search call item. / Id of the file search call item. / Id of the image generation call item. / Id of the code interpreter call item. / Id of the computer call item. / Id of the datetime server tool item. / Id of the web search server tool item. / Id of the code interpreter server tool item. / Id of the file search server tool item. / Id of the image generation server tool item. / Id of the browser use server tool item. / Id of the bash server tool item. / Id of the text editor server tool item. / Id of the apply_patch server tool item. / Id of the apply_patch call item. / Id of the shell call item. / Id of the shell call output item. / Id of the shell server tool item. / Id of the web fetch server tool item. / Id of the tool search server tool item. / Id of the memory server tool item. / Id of the MCP server tool item. / Id of the model search server tool item. / Id of the fusion server tool item. / Id of the advisor server tool item. / Id of the subagent server tool item. / Id of the files server tool item. / Id of the custom tool call item. |
| output[].phase | string | null | The phase of an assistant message. Use `commentary` for an intermediate assistant message and `final_answer` for the final assistant message. For follow-up requests with models like `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages. |
| output[].role | string | Role of the author; always assistant. |
| output[].status | string | Status of the message item. / Status of the reasoning item. / Status of the function call item. / Status of a web search call. / Status of a web search call. / Status of an image generation call. / Status of the code interpreter call. / Status of the computer call item. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call that can fail. / Status of a tool call. / Status of a tool call. / Lifecycle state of an `apply_patch_call` output item. / Status of a shell call or its output. / Status of a shell call or its output. / Status of a tool call that can fail. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call. / Status of a tool call that can fail. / Status of a tool call that can fail. / Status of a tool call. / Status of the custom tool call item. |
| output[].type | string | Always `message`. Discriminator that marks this object as a OutputMessage in a `type`-tagged union. / Always `reasoning`. Discriminator that marks this object as a OutputItemReasoning in a `type`-tagged union. / Always `function_call`. Discriminator that marks this object as a OutputItemFunctionCall in a `type`-tagged union. / Always `web_search_call`. Discriminator that marks this object as a OutputItemWebSearchCall in a `type`-tagged union. / Always `file_search_call`. Discriminator that marks this object as a OutputItemFileSearchCall in a `type`-tagged union. / Always `image_generation_call`. Discriminator that marks this object as a OutputItemImageGenerationCall in a `type`-tagged union. / Always `code_interpreter_call`. Discriminator that marks this object as a OutputItemCodeInterpreterCall in a `type`-tagged union. / Always `computer_call`. Discriminator that marks this object as a OutputComputerCallItem in a `type`-tagged union. / Always `openrouter:datetime`. Discriminator that marks this object as a OutputDatetimeItem in a `type`-tagged union. / Always `openrouter:web_search`. Discriminator that marks this object as a OutputWebSearchServerToolItem in a `type`-tagged union. / Always `openrouter:code_interpreter`. Discriminator that marks this object as a OutputCodeInterpreterServerToolItem in a `type`-tagged union. / Always `openrouter:file_search`. Discriminator that marks this object as a OutputFileSearchServerToolItem in a `type`-tagged union. / Always `openrouter:image_generation`. Discriminator that marks this object as a OutputImageGenerationServerToolItem in a `type`-tagged union. / Always `openrouter:browser_use`. Discriminator that marks this object as a OutputBrowserUseServerToolItem in a `type`-tagged union. / Always `openrouter:bash`. Discriminator that marks this object as a OutputBashServerToolItem in a `type`-tagged union. / Always `openrouter:text_editor`. Discriminator that marks this object as a OutputTextEditorServerToolItem in a `type`-tagged union. / Always `openrouter:apply_patch`. Discriminator that marks this object as a OutputApplyPatchServerToolItem in a `type`-tagged union. / Always `apply_patch_call`. Discriminator that marks this object as a OutputApplyPatchCallItem in a `type`-tagged union. / Always `shell_call`. Discriminator that marks this object as a OutputShellCallItem in a `type`-tagged union. / Always `shell_call_output`. Discriminator that marks this object as a OutputShellCallOutputItem in a `type`-tagged union. / Always `openrouter:shell`. Discriminator that marks this object as a OutputShellServerToolItem in a `type`-tagged union. / Always `openrouter:web_fetch`. Discriminator that marks this object as a OutputWebFetchServerToolItem in a `type`-tagged union. / Always `openrouter:tool_search`. Discriminator that marks this object as a OutputToolSearchServerToolItem in a `type`-tagged union. / Always `openrouter:memory`. Discriminator that marks this object as a OutputMemoryServerToolItem in a `type`-tagged union. / Always `openrouter:mcp`. Discriminator that marks this object as a OutputMcpServerToolItem in a `type`-tagged union. / Always `openrouter:experimental__search_models`. Discriminator that marks this object as a OutputSearchModelsServerToolItem in a `type`-tagged union. / Always `openrouter:fusion`. Discriminator that marks this object as a OutputFusionServerToolItem in a `type`-tagged union. / Always `openrouter:advisor`. Discriminator that marks this object as a OutputAdvisorServerToolItem in a `type`-tagged union. / Always `openrouter:subagent`. Discriminator that marks this object as a OutputSubagentServerToolItem in a `type`-tagged union. / Always `openrouter:files`. Discriminator that marks this object as a OutputFilesServerToolItem in a `type`-tagged union. / Always `custom_tool_call`. Discriminator that marks this object as a OutputCustomToolCallItem in a `type`-tagged union. |
| output[].encrypted_content | string | null | Opaque encrypted reasoning; send it back unchanged to let the model continue its reasoning on the next turn. |
| output[].summary | array<object> | Summary parts of the reasoning. |
| output[].format | string | null | Wire format of the reasoning details, which names the provider family that produced them. |
| output[].signature | string | null | A signature for the reasoning content, used for verification |
| output[].arguments | string | string | null | string | null | string | null | string | string | null | JSON-encoded arguments the model produced for the function. / The raw tool-call arguments string as emitted by the model. / The raw tool-call arguments string as emitted by the model. Echo back unchanged when replaying history; used verbatim to preserve provider prompt-cache prefixes. / The raw tool-call arguments string as emitted by the model. / The JSON arguments submitted to the search tool (e.g. {"query":"Claude"}) / The raw tool-call arguments string as emitted by the model. |
| output[].async | boolean | True when the model called a tool declared with `async: true` and may continue its turn before the output is returned. Return the result in a later request as a `function_call_output` with this `call_id`. |
| output[].call_id | string | string | null | string | string | string | string | string | null | string | string | null | string | Id of the call; the function_call_output item that answers it repeats it as call_id. / Id of the call; the computer_call_output item that answers it repeats it as call_id. / The model-generated tool call id from the originating turn. / Id of the apply_patch tool call. / Id of the call; the apply_patch_call_output item that answers it repeats it as call_id. / Id of the call; the shell_call_output item that answers it repeats it as call_id. / Id of the shell call this output answers. / The model-generated tool call id from the originating turn. / EXPERIMENTAL — subject to change without notice. The `call_id` of the tool call that spawned this subagent. This id will also be included as the `subagent_id` on any `function_call` items created by the subagent. This must be returned in the request so the `function_call` can be matched with the correct subagent. A suspended `in_progress` item is announced once and never re-emitted or terminally closed — completion arrives as a new item with the same `call_id`. / The model-generated tool call id from the originating turn. / Id of the call; the custom_tool_call_output item that answers it repeats it as call_id. |
| output[].name | string | Name of the function being called. / Configured name of the subagent that executed the task (the `name` on its tool entry). Present only for named subagents; omitted for an unnamed (default) subagent. / Name of the custom tool being called. |
| output[].namespace | string | Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) |
| output[].subagent_id | string | EXPERIMENTAL — subject to change without notice. String id that matches the `call_id` of the `openrouter:subagent` server tool call that spawned the subagent. Present on every `function_call` item the subagent projects; absent on ordinary function calls. |
| output[].subagent_items | array<object> | EXPERIMENTAL — subject to change without notice. The subagent's output items produced on this turn. Treat this as an opaque object; you must replay it in the request so that the subagent can continue execution of the tool with the same context. If a subagent created multiple parallel tool calls, only the first tool call will have this field. The other tool calls will only have `subagent_id`. Present only if the tool call originates from a subagent spawned by the `openrouter:subagent` server tool. |
| output[].action | object | any | object | string | object | object | string | The search action the model took: a search, opening a page, or finding a pattern in a page. / The action the model asks the client to perform on the computer. / The search action performed, matching OpenAI web_search_call.action shape. Includes the query the model issued and optional source URLs returned by the search provider. / The browser action that was performed. / The commands the model asks the client to run. / The commands that were run. / Memory action that was performed. |
| output[].queries | array<string> | Queries the model ran against the vector stores. / Queries that ran against the vector stores. |
| output[].result | string | null | string | Base64-encoded generated image; null while generation has not finished. / The generated image as a base64-encoded string or URL, matching OpenAI image_generation_call format / JSON-serialized result of the file operation. |
| output[].prompt | string | The prompt (possibly rewritten) that the image was generated from. / The prompt the executor sent to the advisor. |
| output[].code | string | null | string | The code the interpreter ran; null while it is still being written. / The code that ran. |
| output[].container_id | string | Id of the container the code ran in. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. / The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed. |
| output[].outputs | array | null | Outputs of the run: logs and images; null while the run has not finished. |
| output[].pending_safety_checks | array<object> | Safety checks that must be acknowledged before the action is performed. |
| output[].datetime | string | ISO 8601 datetime string |
| output[].timezone | string | IANA timezone name |
| output[].exitCode | integer | Exit code of the run; 0 means success. / Exit code of the command; 0 means success. |
| output[].language | string | Language of the code that ran. |
| output[].stderr | string | Standard error output of the code. / Standard error output of the command. |
| output[].stdout | string | Standard output of the code. / Standard output of the command. |
| output[].imageB64 | string | Base64-encoded generated image. |
| output[].imageUrl | string | URL of the generated image. |
| output[].revisedPrompt | string | Prompt after the image model rewrote it. |
| output[].screenshotB64 | string | Base64-encoded screenshot taken after the action. |
| output[].command | string | The bash command that ran. / Editor command that ran. |
| output[].error | string | The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. A non-zero `exitCode` is a command failure, not a tool failure. / The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'incomplete'` and an empty `output`; absent on a successful call. / The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. `output` is omitted when `error` is set. / The error message if the fetch failed. / Error message when the fusion run did not produce an analysis result. / Error message when the advisor call did not produce advice. Set together with `status: 'failed'` on the terminal item. / Error message when the subagent task did not produce an outcome. Set together with `status: 'failed'` on the terminal item. / Error message when the file operation failed. |
| output[].files | array<object> | Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API. |
| output[].filePath | string | Path of the file the command worked on. |
| output[].operation | object | string | The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. / The file operation performed (list, read, write, or edit). |
| output[].max_output_length | integer | null | Maximum number of characters of output that was kept; null for no limit. |
| output[].output | array<object> | Output of each command, in the order the commands ran. |
| output[].httpStatus | integer | The HTTP status code returned by the upstream URL fetch. |
| output[].title | string | Title of the fetched page. |
| output[].url | string | URL that was fetched. |
| output[].query | string | The tool search query. / The model search query. |
| output[].key | string | Key of the memory entry. |
| output[].value | any | Value of the memory entry; absent for reads that found nothing and for deletes. |
| output[].serverLabel | string | Label of the MCP server. |
| output[].toolName | string | Name of the MCP tool that was called. |
| output[].analysis | object | Structured analysis produced by the fusion analyst model. |
| output[].failed_models | array<object> | Models that were requested as part of the analysis panel but did not produce a response. Present when at least one requested analysis model failed. The fusion result is still usable but was produced from a degraded panel. |
| output[].failure_reason | string | Typed failure reason when the fusion run failed. Possible values include: all_panels_failed, insufficient_credits, rate_limited, invalid_model, judge_not_valid_json, judge_schema_mismatch, judge_upstream_error, judge_empty_completion. The four analysis-stage codes keep their pre-rename `judge_` spelling so existing consumers keep matching. The consumer-cancellation code is `cancelled`. |
| output[].responses | array<object> | Analysis models that produced a response in this fusion run, with each model's full panel content. |
| output[].sources | array<object> | Web pages the analysis panels and analyst retrieved via web search during this fusion run, deduplicated by URL across the whole run. Present when at least one model cited a source. |
| output[].advice | string | The advisor model's response (the advice text returned to the executor). |
| output[].instance_name | string | Provider-safe function name of the specific advisor instance that produced this item (e.g. `openrouter_advisor__1`). Present only when more than one advisor tool is configured; omitted for the default single advisor. Echo this field back unchanged so the advisor's cross-request memory stays namespaced to the correct instance. This identity is positional: it is derived from the index of the advisor entry in the request `tools` array, so clients must keep the order of advisor tool entries stable across requests in a conversation. Reordering or inserting advisor entries shifts these names and causes each advisor's cross-request memory to be attributed to the wrong instance. / Provider-safe function name of the specific subagent instance that produced this item (e.g. `openrouter_subagent__1`). Present only on items from non-default instances — the second and later subagent entries in the request `tools` array. The first (default) instance omits it, even when multiple subagents are configured. When a replayed item echoes this field back, the transcript rehydrates the call under that instance's tool. This identity is positional: it is derived from the index of the subagent entry in the request `tools` array, so keep the order of subagent entries stable across requests in a conversation. |
| output[].model | string | Slug of the advisor model that was consulted. / Slug of the worker model that executed the task. |
| output[].outcome | string | The worker model's result (the outcome text returned to the delegating model). |
| output[].task_description | string | The task description the delegating model sent to the worker. |
| output[].task_name | string | The short task identifier the delegating model supplied. |
| output[].file_id | string | The target file id supplied in the tool-call arguments. |
| output[].filename | string | The target filename supplied in the tool-call arguments. |
| output[].input | string | Free-form input the model produced for the custom tool. |
| output_text | string | Convenience concatenation of all output text of the response. |
| parallel_tool_calls | boolean | Whether the model was allowed to call several tools in one turn. |
| presence_penalty | number | null | The presence penalty that applied to the request, if any. |
| previous_response_id | string | null | Id of the response this one continued; null when it started a new conversation. |
| prompt | object | null | Reference to a stored prompt template with its variables. |
| prompt.id | string | Id of the stored prompt template. |
| prompt.variables | object | null | Values for the template variables, keyed by variable name; a value is a string or an input text, image or file part. |
| prompt_cache_key | string | null | Cache key the request supplied to improve prompt cache hits; null when none was set. |
| prompt_cache_options | object | null | Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. |
| prompt_cache_options.mode | string | Prompt cache mode; explicit caches only the blocks marked with prompt_cache_breakpoint. |
| prompt_cache_options.ttl | string | null | Lifetime of cache entries, for example 30m; null leaves the provider default. |
| reasoning | object | null | Reasoning settings that applied: effort, summary verbosity, mode and context. |
| reasoning.context | string | null | Controls which reasoning is available to the model. `auto` uses the model default (same as omitting); `all_turns` includes reasoning from earlier turns passed in input; `current_turn` limits to the current turn only. Only supported by OpenAI GPT-5.6 and newer. |
| reasoning.effort | string | null | How much reasoning the model should spend. |
| reasoning.mode | string | null | Selects the reasoning mode. `standard` is the default; `pro` engages deeper reasoning on models that support it, billed at standard token rates. Only supported by OpenAI GPT-5.6 and newer. |
| reasoning.summary | string | null | How detailed the reasoning summary should be. |
| safety_identifier | string | null | End-user identifier the request supplied for abuse monitoring; null when none was set. |
| service_tier | string | null | Service tier the provider used for the response; null when not reported. |
| status | string | Lifecycle status of the response. |
| store | boolean | Whether the response is stored so it can be retrieved later. |
| temperature | number | null | Sampling temperature that applied to the request, if any. |
| text | object | Text output configuration including format and verbosity |
| text.format | object | Text response format configuration |
| text.verbosity | string | null | How long the answer should be. |
| tool_choice | string | object | How the model picks tools: a mode string or a specific tool. |
| tool_choice.name | string | Name of the function or tool the model must call. |
| tool_choice.type | string | Kind of tool the model must call. / Always `allowed_tools`. Discriminator that marks this object as a ToolChoiceAllowed in a `type`-tagged union. / Kind of tool the model must call. / Kind of tool the model must call. |
| tool_choice.mode | string | auto lets the model pick among the allowed tools or none; required forces a call to one of them. |
| tool_choice.tools | array<object> | The allowed tools, each as a tool reference such as {type: function, name}. |
| tools | array<object> | Tools that were available to the model for this response. |
| tools[].description | string | null | string | string | What the function does and when to use it; the model reads this to decide whether to call it. / What the custom tool does and when to use it. / What the group of tools is for. |
| tools[].name | string | Name of the function; the model uses it in function_call items. / Name of the custom tool. / Name of the namespace that groups the tools. |
| tools[].parameters | object | null | JSON Schema of the function arguments; null when the function takes none. |
| tools[].strict | boolean | null | Whether to enforce strict argument validation against the schema; null leaves the provider default. |
| tools[].type | string | Always `function`. Discriminator that marks this object as a FunctionTool in a `type`-tagged union. / Always `web_search_preview`. Discriminator that marks this object as a Preview_WebSearchServerTool in a `type`-tagged union. / Always `web_search_preview_2025_03_11`. Discriminator that marks this object as a Preview_20250311_WebSearchServerTool in a `type`-tagged union. / Always `web_search`. Discriminator that marks this object as a Legacy_WebSearchServerTool in a `type`-tagged union. / Always `web_search_2025_08_26`. Discriminator that marks this object as a WebSearchServerTool in a `type`-tagged union. / Comparison operator. / Always `computer_use_preview`. Discriminator that marks this object as a ComputerUseServerTool in a `type`-tagged union. / Always `code_interpreter`. Discriminator that marks this object as a CodeInterpreterServerTool in a `type`-tagged union. / Always `mcp`. Discriminator that marks this object as a McpServerTool in a `type`-tagged union. / Always `image_generation`. Discriminator that marks this object as a ImageGenerationServerTool in a `type`-tagged union. / Always `local_shell`. Discriminator that marks this object as a CodexLocalShellTool in a `type`-tagged union. / Always `shell`. Discriminator that marks this object as a ShellServerTool in a `type`-tagged union. / Always `apply_patch`. Discriminator that marks this object as a ApplyPatchServerTool in a `type`-tagged union. / Always `custom`. Discriminator that marks this object as a CustomTool in a `type`-tagged union. / Always `namespace`. Discriminator that marks this object as a NamespaceTool in a `type`-tagged union. |
| tools[].async | boolean | Lets the model keep working after calling this tool instead of waiting for its output. The tool is still executed by the client; return the result in a later request as a `function_call_output` with the original `call_id`. Only honored by providers whose Responses API supports async tools; ignored elsewhere. |
| tools[].defer_loading | boolean | Withhold this tool from the model until `openrouter:tool_search` finds it. Requires the tool search server tool; at least one tool must remain non-deferred. |
| tools[].engine | string | Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). |
| tools[].filters | object | null | Restricts web search by domain. / Attribute filter applied to the search: a comparison or a compound filter. |
| tools[].max_results | integer | Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped. |
| tools[].max_uses | integer | Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded only to Anthropic (as `max_uses`); other native search providers have no equivalent parameter and ignore it. |
| tools[].mode | string | Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored. |
| tools[].search_context_size | string | Size of the search context for web search tools |
| tools[].user_location | object | null | Approximate location of the user, used to bias web search results. / User location information for web search / User location information for web search |
| tools[].max_num_results | integer | Maximum number of results to return, between 1 and 50. |
| tools[].ranking_options | object | Ranking options for the search. |
| tools[].vector_store_ids | array<string> | Ids of the vector stores to search. |
| tools[].display_height | integer | Height of the computer display in pixels. |
| tools[].display_width | integer | Width of the computer display in pixels. |
| tools[].environment | string | Kind of environment that is controlled. |
| tools[].container | string | object | Container for the code to run in: a container id or an automatic container with files. |
| tools[].allowed_tools | array<string> | object | null | Tools of the server the model may use: a list of names or a filter. |
| tools[].authorization | string | OAuth access token for the MCP server. |
| tools[].connector_id | string | Id of a built-in connector; give this or server_url. |
| tools[].headers | object | null | HTTP headers sent to the MCP server; null for none. |
| tools[].require_approval | object | string | null | Whether tool calls need approval before they run: always, never, or a filter per tool. |
| tools[].server_description | string | What the MCP server is for, which helps the model decide when to use it. |
| tools[].server_label | string | Label that names the MCP server in the conversation. |
| tools[].server_url | string | URL of the MCP server; give this or connector_id. |
| tools[].background | string | Background of the generated image. |
| tools[].input_fidelity | string | null | How closely to preserve details of input images; null uses the default. |
| tools[].input_image_mask | object | Mask that marks the region of the input image to edit. |
| tools[].model | string | Image model to use. |
| tools[].moderation | string | Moderation level applied to the generated image. |
| tools[].output_compression | integer | Compression level from 0 to 100 for jpeg and webp output. |
| tools[].output_format | string | File format of the generated image. |
| tools[].partial_images | integer | Number of partial images to stream while generating, from 0 to 3. |
| tools[].quality | string | Quality of the generated image. |
| tools[].size | string | Size of the generated image; auto lets the model choose. |
| tools[].format | object | Format of the tool input: free text or a grammar. |
| tools[].tools | array<object> | Function tools in the namespace. |
| top_logprobs | integer | Number of most likely tokens whose log probabilities were requested per position. |
| top_p | number | null | Nucleus sampling value that applied to the request, if any. |
| truncation | string | null | How to handle input that exceeds the context window. |
| usage | object | null | Token usage information for the response |
| usage.input_tokens | integer | Number of input tokens, cached tokens included. |
| usage.input_tokens_details | object | Breakdown of the input tokens. |
| usage.output_tokens | integer | Number of output tokens, reasoning tokens included. |
| usage.output_tokens_details | object | Breakdown of the output tokens. |
| usage.total_tokens | integer | Input plus output tokens. |
| usage.cost | number | null | Cost of the completion |
| usage.cost_details | object | Breakdown of the upstream inference cost. |
| usage.is_byok | boolean | Whether a request was made using a Bring Your Own Key configuration |
| usage.server_tool_use_details | object | null | Usage for server-side tool execution (e.g., web search) |
| user | string | null | End-user identifier the request supplied; null when none was set. |
| error_type | string | Canonical OpenRouter error type, stable across all API formats |
| openrouter_metadata | object | Routing report: what was requested, how the router chose, and what was attempted. |
| openrouter_metadata.attempt | integer | Number of the attempt that served the request, starting at 1. |
| openrouter_metadata.attempts | array<object> | Every attempt that was made, in order. |
| openrouter_metadata.endpoints | object | Which endpoints were available and which one was chosen. |
| openrouter_metadata.generation_time | integer | Milliseconds measured for the generation, from dispatching the upstream request until its response body ended. Divide the completion token count by this for throughput. Absent when no upstream request was dispatched. |
| openrouter_metadata.is_byok | boolean | Whether the request used a key supplied by the caller. |
| openrouter_metadata.params | object | Router parameters that applied to the request. |
| openrouter_metadata.pipeline | array<object> | Stages the request went through before and after the model call. |
| openrouter_metadata.region | string | null | Region that served the request; null when unknown. |
| openrouter_metadata.requested | string | The model or alias the request asked for. |
| openrouter_metadata.strategy | string | How the router picked the model or provider for this request. |
| openrouter_metadata.summary | string | One-line summary of the routing decision. |
**text/event-stream — chunk / 事件对象**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | object | Union of all possible event types emitted during response streaming |
| data.response | object | Complete non-streaming response from the Responses API |
| data.sequence_number | integer | Position of this event in the stream. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream; it increases with every event, so use it to order events or detect a gap. / Position of this event in the stream. |
| data.type | string | Always `response.created`. Discriminator that marks this object as a CreatedEvent in a `type`-tagged union. / Always `response.in_progress`. Discriminator that marks this object as a InProgressEvent in a `type`-tagged union. / Always `response.completed`. Discriminator that marks this object as a CompletedEvent in a `type`-tagged union. / Always `response.incomplete`. Discriminator that marks this object as a IncompleteEvent in a `type`-tagged union. / Always `response.failed`. Discriminator that marks this object as a FailedEvent in a `type`-tagged union. / Always `error`. Discriminator that marks this object as a BaseErrorEvent in a `type`-tagged union. / Always `response.output_item.added`. Discriminator that marks this object as a OutputItemAddedEvent in a `type`-tagged union. / Always `response.output_item.done`. Discriminator that marks this object as a OutputItemDoneEvent in a `type`-tagged union. / Always `response.content_part.added`. Discriminator that marks this object as a BaseContentPartAddedEvent in a `type`-tagged union. / Always `response.content_part.done`. Discriminator that marks this object as a BaseContentPartDoneEvent in a `type`-tagged union. / Always `response.output_text.delta`. Discriminator that marks this object as a BaseTextDeltaEvent in a `type`-tagged union. / Always `response.output_text.done`. Discriminator that marks this object as a BaseTextDoneEvent in a `type`-tagged union. / Always `response.refusal.delta`. Discriminator that marks this object as a BaseRefusalDeltaEvent in a `type`-tagged union. / Always `response.refusal.done`. Discriminator that marks this object as a BaseRefusalDoneEvent in a `type`-tagged union. / Always `response.output_text.annotation.added`. Discriminator that marks this object as a BaseAnnotationAddedEvent in a `type`-tagged union. / Always `response.function_call_arguments.delta`. Discriminator that marks this object as a BaseFunctionCallArgsDeltaEvent in a `type`-tagged union. / Always `response.function_call_arguments.done`. Discriminator that marks this object as a BaseFunctionCallArgsDoneEvent in a `type`-tagged union. / Always `response.reasoning_text.delta`. Discriminator that marks this object as a BaseReasoningDeltaEvent in a `type`-tagged union. / Always `response.reasoning_text.done`. Discriminator that marks this object as a BaseReasoningDoneEvent in a `type`-tagged union. / Always `response.reasoning_summary_part.added`. Discriminator that marks this object as a BaseReasoningSummaryPartAddedEvent in a `type`-tagged union. / Always `response.reasoning_summary_part.done`. Discriminator that marks this object as a BaseReasoningSummaryPartDoneEvent in a `type`-tagged union. / Always `response.reasoning_summary_text.delta`. Discriminator that marks this object as a BaseReasoningSummaryTextDeltaEvent in a `type`-tagged union. / Always `response.reasoning_summary_text.done`. Discriminator that marks this object as a BaseReasoningSummaryTextDoneEvent in a `type`-tagged union. / Always `response.image_generation_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesImageGenCallInProgress in a `type`-tagged union. / Always `response.image_generation_call.generating`. Discriminator that marks this object as a OpenAIResponsesImageGenCallGenerating in a `type`-tagged union. / Always `response.image_generation_call.partial_image`. Discriminator that marks this object as a OpenAIResponsesImageGenCallPartialImage in a `type`-tagged union. / Always `response.image_generation_call.completed`. Discriminator that marks this object as a OpenAIResponsesImageGenCallCompleted in a `type`-tagged union. / Always `response.code_interpreter_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallInProgress in a `type`-tagged union. / Always `response.code_interpreter_call.interpreting`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallInterpreting in a `type`-tagged union. / Always `response.code_interpreter_call.completed`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCompleted in a `type`-tagged union. / Always `response.code_interpreter_call_code.delta`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCodeDelta in a `type`-tagged union. / Always `response.code_interpreter_call_code.done`. Discriminator that marks this object as a OpenAIResponsesCodeInterpreterCallCodeDone in a `type`-tagged union. / Always `response.web_search_call.in_progress`. Discriminator that marks this object as a OpenAIResponsesWebSearchCallInProgress in a `type`-tagged union. / Always `response.web_search_call.searching`. Discriminator that marks this object as a OpenAIResponsesWebSearchCallSearching in a `type`-tagged union. / Always `response.web_search_call.completed`. Discriminator that marks this object as a OpenAIResponsesSearchCompleted in a `type`-tagged union. / Always `response.custom_tool_call_input.delta`. Discriminator that marks this object as a BaseCustomToolCallInputDeltaEvent in a `type`-tagged union. / Always `response.custom_tool_call_input.done`. Discriminator that marks this object as a BaseCustomToolCallInputDoneEvent in a `type`-tagged union. / Always `response.apply_patch_call_operation_diff.delta`. Discriminator that marks this object as a ApplyPatchCallOperationDiffDeltaEvent in a `type`-tagged union. / Always `response.apply_patch_call_operation_diff.done`. Discriminator that marks this object as a ApplyPatchCallOperationDiffDoneEvent in a `type`-tagged union. / Always `response.fusion_call.in_progress`. Discriminator that marks this object as a FusionCallInProgressEvent in a `type`-tagged union. / Always `response.fusion_call.panel.added`. Discriminator that marks this object as a FusionCallPanelAddedEvent in a `type`-tagged union. / Always `response.fusion_call.panel.delta`. Discriminator that marks this object as a FusionCallPanelDeltaEvent in a `type`-tagged union. / Always `response.fusion_call.panel.reasoning.delta`. Discriminator that marks this object as a FusionCallPanelReasoningDeltaEvent in a `type`-tagged union. / Always `response.fusion_call.panel.completed`. Discriminator that marks this object as a FusionCallPanelCompletedEvent in a `type`-tagged union. / Always `response.fusion_call.panel.failed`. Discriminator that marks this object as a FusionCallPanelFailedEvent in a `type`-tagged union. / Always `response.fusion_call.analysis.in_progress`. Discriminator that marks this object as a FusionCallAnalysisInProgressEvent in a `type`-tagged union. / Always `response.fusion_call.analysis.completed`. Discriminator that marks this object as a FusionCallAnalysisCompletedEvent in a `type`-tagged union. / Always `response.fusion_call.completed`. Discriminator that marks this object as a FusionCallCompletedEvent in a `type`-tagged union. / Always `response.debug`. Discriminator that marks this object as a DebugEvent in a `type`-tagged union. |
| data.code | string | null | string | Error code; null when the upstream gave none. / The complete code the interpreter runs. |
| data.message | string | Human-readable error message. |
| data.param | string | null | Name of the request parameter the error is about; null when it is not about a parameter. |
| data.item | object | An output item from the response |
| data.output_index | integer | Index of the item in the response output array that this event belongs to. |
| data.content_index | integer | Index of the content part inside the output item that this event belongs to. |
| data.item_id | string | Id of the output item this event belongs to; it equals the id of that item in the response output. |
| data.part | object | The content part as it starts: output text or refusal. / The content part in its final form: output text or refusal. / A reasoning summary part. / A reasoning summary part. |
| data.delta | string | Text fragment to append to the output text of this content part. / Refusal text fragment to append. / Fragment of the JSON-encoded function arguments to append. / Reasoning text fragment to append. / Reasoning summary text fragment to append. / Fragment of the code the interpreter will run, to append. / Fragment of the custom tool call input to append. / Fragment of the patch diff to append. / Text fragment the panel model produced. / Reasoning text fragment the panel model produced. |
| data.logprobs | array<object> | Log probabilities of the tokens in this fragment, when requested. / Log probabilities of the tokens in the complete text, when requested. |
| data.text | string | The complete output text of this content part. / The complete reasoning text of this content part. / The complete reasoning summary text of this part. |
| data.refusal | string | The complete refusal text. |
| data.annotation | object | Annotation attached to output text: a file citation, URL citation or file path. |
| data.annotation_index | integer | Index of the new annotation inside the content part's annotations array. |
| data.arguments | string | The complete JSON-encoded arguments of the function call. |
| data.name | string | Name of the function being called. |
| data.summary_index | integer | Index of the reasoning summary part inside the reasoning item that this event belongs to. |
| data.partial_image_b64 | string | Base64-encoded partial image produced while generation is still running. |
| data.partial_image_index | integer | Zero-based index of this partial image among the partial images of the call. |
| data.input | string | The complete input of the custom tool call. |
| data.diff | string | The complete patch diff. |
| data.model | string | Slug of the panel model that started. / Slug of the panel model that produced the fragment. / Slug of the panel model that produced the fragment. / Slug of the panel model that finished. / Slug of the panel model that failed. |
| data.content | string | The complete answer of the panel model. |
| data.error | string | Error message that explains why the panel model failed. |
| data.status_code | integer | HTTP status code of the failed upstream call, when one is available. |
| data.analyst_model | string | Slug of the model producing the structured analysis. |
| data.judge_model | string | Deprecated alias of `analyst_model`, kept so existing consumers keep working. Always carries the same value. Use `analyst_model`. |
| data.analysis | object | Structured analysis produced by the fusion analyst model. |
| data.debug | object | Debug information. |
# 读取响应
先调用「生成响应」，用返回的 ID 替换 resp\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
# 删除响应
先调用「生成响应」，用返回的 ID 替换 resp\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API delete response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
#
先调用「生成响应」，用返回的 ID 替换 resp\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API cancel response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
# 列出响应输入项
先调用「生成响应」，用返回的 ID 替换 resp\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API input item list
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API compact response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Native Responses API input token count
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
# 创建会话
## 响应 [#响应]
### HTTP 200 [#http-200]
The created conversation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
# 读取会话
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The conversation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
# 更新会话
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The updated conversation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
# 删除会话
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Deletion confirmation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| object | string | |
| deleted | boolean | |
# 创建会话条目
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The items just added
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| object | string | Object type; always `list`. |
| data | array<object> | Items of the conversation, in the order the list requested. |
| first_id | string | Id of the first item of this page; null for an empty page. |
| last_id | string | Id of the last item of this page; null for an empty page. |
| has_more | boolean | Whether more items exist beyond this page; pass `last_id` as `after` to read them. |
# 列出会话条目
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The conversation's items
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| object | string | Object type; always `list`. |
| data | array<object> | Items of the conversation, in the order the list requested. |
| first_id | string | Id of the first item of this page; null for an empty page. |
| last_id | string | Id of the last item of this page; null for an empty page. |
| has_more | boolean | Whether more items exist beyond this page; pass `last_id` as `after` to read them. |
# 读取会话条目
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。 条目 ID 取自「添加对话条目」或「列出对话条目」，替换 item\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The item
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
# 删除会话条目
先调用「创建对话」拿到 conv\_ 开头的 ID，替换 conv\_123。 条目 ID 取自「添加对话条目」或「列出对话条目」，替换 item\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The conversation, with the item removed
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the conversation, such as `conv_...`; use it as `conversation_id` in conversation calls and as `conversation` in createResponse. |
| object | string | Object type; always `conversation`. |
| created_at | integer | Unix time in seconds at which the conversation was created. |
| metadata | object | Up to 16 string key/value pairs; keys at most 64 characters and values at most 512. |
# 生成图像
## 响应 [#响应]
### HTTP 200 [#http-200]
Image generation response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| created | integer | |
| data | array<object> | |
| data[].url | string | |
| data[].b64_json | string | |
| data[].revised_prompt | string | |
# 列出模型
## 响应 [#响应]
### HTTP 200 [#http-200]
Returns a list of models or RSS feed
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | List of available models |
| data[].alias_target | object | Concrete model targeted by this tilde-latest alias, when applicable |
| data[].architecture | object | Model architecture information |
| data[].benchmarks | object | Third-party benchmark rankings for this model. Omitted when no benchmark data is available. |
| data[].canonical_slug | string | Canonical slug for the model |
| data[].context_length | integer | null | Maximum context length in tokens |
| data[].created | integer | Unix timestamp of when the model was created |
| data[].default_parameters | object | null | Default parameters for this model |
| data[].description | string | Description of the model |
| data[].expiration_date | string | null | The date after which the model may be removed. ISO 8601 date string (YYYY-MM-DD) or null if no expiration. |
| data[].hugging_face_id | string | null | Hugging Face model identifier, if applicable |
| data[].id | string | Unique identifier for the model |
| data[].knowledge_cutoff | string | null | The date up to which the model was trained on data. ISO 8601 date string (YYYY-MM-DD) or null if unknown. |
| data[].links | object | Related API endpoints and resources for this model. |
| data[].name | string | Display name of the model |
| data[].per_request_limits | object | null | Per-request token limits |
| data[].pricing | object | Pricing information for the model |
| data[].reasoning | object | Reasoning effort configuration. Omitted for non-reasoning models and dynamic router models. |
| data[].supported_parameters | array<string> | List of supported parameters for this model |
| data[].supported_voices | array | null | List of supported voice identifiers for TTS models. Null for non-TTS models. |
| data[].top_provider | object | Information about the top provider for this model |
| links | object | Pagination links |
| links.next | string | null | URL for the next page of results, or null if this is the last page |
| total_count | integer | Total number of models matching the query |
# 读取模型
## 响应 [#响应]
### HTTP 200 [#http-200]
The matching OpenRouter model list entry.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| alias_target | object | Concrete model targeted by this tilde-latest alias, when applicable |
| alias_target.name | string | Human-readable name of the concrete model targeted by this alias |
| alias_target.slug | string | Routable model ID of the concrete target, matching that model row's id |
| architecture | object | Model architecture information |
| architecture.input_modalities | array<string> | Supported input modalities |
| architecture.instruct_type | string | null | Instruction format type |
| architecture.modality | string | null | Primary modality of the model |
| architecture.output_modalities | array<string> | Supported output modalities |
| architecture.tokenizer | string | Tokenizer type used by the model |
| benchmarks | object | Third-party benchmark rankings for this model. Omitted when no benchmark data is available. |
| benchmarks.artificial_analysis | object | Artificial Analysis benchmark index scores. |
| benchmarks.design_arena | array<object> | Design Arena ELO rankings across arena+category pairs. |
| canonical_slug | string | Canonical slug for the model |
| context_length | integer | null | Maximum context length in tokens |
| created | integer | Unix timestamp of when the model was created |
| default_parameters | object | null | Default parameters for this model |
| default_parameters.frequency_penalty | number | null | |
| default_parameters.presence_penalty | number | null | |
| default_parameters.repetition_penalty | number | null | |
| default_parameters.temperature | number | null | |
| default_parameters.top_k | integer | null | |
| default_parameters.top_p | number | null | |
| description | string | Description of the model |
| expiration_date | string | null | The date after which the model may be removed. ISO 8601 date string (YYYY-MM-DD) or null if no expiration. |
| hugging_face_id | string | null | Hugging Face model identifier, if applicable |
| id | string | Unique identifier for the model |
| knowledge_cutoff | string | null | The date up to which the model was trained on data. ISO 8601 date string (YYYY-MM-DD) or null if unknown. |
| links | object | Related API endpoints and resources for this model. |
| links.details | string | URL for the model details/endpoints API |
| name | string | Display name of the model |
| per_request_limits | object | null | Per-request token limits |
| per_request_limits.completion_tokens | number | Maximum completion tokens per request |
| per_request_limits.prompt_tokens | number | Maximum prompt tokens per request |
| pricing | object | Pricing information for the model |
| pricing.audio | string | Price in USD per audio input token |
| pricing.audio_output | string | Price in USD per audio output token |
| pricing.completion | string | Price in USD per token for completion (output) generation |
| pricing.discount | number | Fractional discount applied to this endpoint's pricing; the price is multiplied by (1 - discount) (0 = no discount, 1 = free) |
| pricing.image | string | Price in USD per image; present only for a flat registry price |
| pricing.image_output | string | Price in USD per output image |
| pricing.image_token | string | Price in USD per image token |
| pricing.input_audio_cache | string | Price in USD per cached audio input token |
| pricing.input_cache_read | string | Price in USD per cached input token (read) |
| pricing.input_cache_write | string | Price per cache-write token, in USD per token. For providers with multiple cache TTLs (e.g. Anthropic), this is the default (5-minute) cache-write rate. |
| pricing.input_cache_write_1h | string | Price per 1-hour cache-write token, in USD per token. Only present for providers that price an extended (1-hour) cache TTL separately, such as Anthropic. |
| pricing.internal_reasoning | string | Price in USD per internal reasoning token |
| pricing.overrides | array<object> | Conditional overrides of the base pricing (e.g. long-context or time-based pricing). An entry applies when all of its condition fields (e.g. min_prompt_tokens, or the utc_start/utc_end time window) match the request; among applicable entries, later entries win per key; price keys absent from an entry inherit the base price. The top-level pricing keys always reflect the price that applies under default conditions. |
| pricing.prompt | string | Price in USD per token for prompt (input) processing |
| pricing.request | string | Price in USD per request |
| pricing.web_search | string | Price in USD per web search |
| pricing.video_second | string | Praxis extension: USD per second of output video. |
| pricing.audio_input_minute | string | Praxis extension: USD per minute of input audio. |
| pricing.audio_output_minute | string | Praxis extension: USD per minute of output audio. |
| pricing.input_character | string | Praxis extension: USD per input character. |
| pricing.page | string | Praxis extension: USD per OCR page. |
| reasoning | object | Reasoning effort configuration. Omitted for non-reasoning models and dynamic router models. |
| reasoning.default_effort | string | null | Default reasoning effort when the client enables reasoning without specifying effort. Maps to `reasoning.effort` in chat requests. When `"none"`, prefer omitting effort unless the user explicitly disables reasoning. |
| reasoning.default_enabled | boolean | Default reasoning enabled state when the client does not set `reasoning.enabled`. |
| reasoning.mandatory | boolean | When true, reasoning cannot be disabled and effort "none" is rejected. |
| reasoning.supported_efforts | array | null | Allowed reasoning effort values for this model, in descending effort order (highest first). Null means no allowlist — all gateway effort values are accepted. |
| reasoning.supports_max_tokens | boolean | Present and `true` when the model accepts `reasoning.max_tokens` in requests (Anthropic-style) instead of or in addition to `reasoning.effort`. Omitted otherwise. |
| supported_parameters | array<string> | List of supported parameters for this model |
| supported_voices | array | null | List of supported voice identifiers for TTS models. Null for non-TTS models. |
| top_provider | object | Information about the top provider for this model |
| top_provider.context_length | integer | null | Context length from the top provider |
| top_provider.is_moderated | boolean | Whether the top provider moderates content |
| top_provider.max_completion_tokens | integer | null | Maximum completion tokens from the top provider. Input and output tokens share the context window, so the effective maximum output for a request is further limited by the context remaining after input tokens. |
# 文本向量
## 响应 [#响应]
### HTTP 200 [#http-200]
Embedding response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | List of embedding objects |
| data[].embedding | array<number> | string | Embedding vector as an array of floats or a base64 string |
| data[].index | integer | Index of the embedding in the input list |
| data[].object | string | |
| id | string | Unique identifier for the embeddings response |
| model | string | The model used for embeddings |
| object | string | |
| usage | object | Token usage statistics |
| usage.cost | number | Cost of the request in credits |
| usage.cost_details | object | null | Breakdown of upstream inference costs |
| usage.is_byok | boolean | Whether a request was made using a Bring Your Own Key configuration |
| usage.prompt_tokens | integer | Number of tokens in the input |
| usage.prompt_tokens_details | object | Per-modality token breakdown. Only present when the input contains 2+ modalities (e.g. text + image) and the upstream provider returns modality-level usage data. Only non-zero modality counts are included. |
| usage.total_tokens | integer | Total number of tokens used |
**text/event-stream — chunk / 事件对象**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string | Not used for embeddings - embeddings do not support streaming |
# 创建视频
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| object | string | Object type; always `video`. |
| model | string | Model that generates the video. |
| status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| created_at | integer | Unix time in seconds at which the job was created. |
| completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| prompt | string | null | Prompt the job was created with. |
| remixed_from_video_id | null | Always null; remix is not supported. |
| error | object | null | Why the job failed; null unless status is `failed`. |
| error.code | string | Machine-readable failure code. |
| error.message | string | Human-readable failure message. |
| polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| usage | object | Cost of the job; present once a price applies. |
| usage.cost | number | Cost of the job in USD: delivered seconds times the per-second price once completed, 0 while running. |
# 列出视频
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| object | string | Object type; always `list`. |
| data | array<object> | Video jobs of the caller, newest first by default. |
| data[].id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| data[].object | string | Object type; always `video`. |
| data[].model | string | Model that generates the video. |
| data[].status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| data[].progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| data[].created_at | integer | Unix time in seconds at which the job was created. |
| data[].completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| data[].expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| data[].seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| data[].size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| data[].prompt | string | null | Prompt the job was created with. |
| data[].remixed_from_video_id | null | Always null; remix is not supported. |
| data[].error | object | null | Why the job failed; null unless status is `failed`. |
| data[].polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| data[].unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| data[].usage | object | Cost of the job; present once a price applies. |
| has_more | boolean | Whether more jobs exist beyond this page; pass `last_id` as `after` to read them. |
| first_id | string | null | Id of the first job in this page; null for an empty page. |
| last_id | string | null | Id of the last job in this page; null for an empty page. |
# 读取视频
先调用「创建视频」，用返回的 ID 替换 video\_123；下载前须轮询至 completed。
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the video job; pass it as `video_id` to retrieve, download or delete it. |
| object | string | Object type; always `video`. |
| model | string | Model that generates the video. |
| status | string | Lifecycle of the job. Poll until it is `completed` or `failed`. |
| progress | integer | Progress from 0 to 100. It is 0 until the job completes and 100 once it has. |
| created_at | integer | Unix time in seconds at which the job was created. |
| completed_at | integer | null | Unix time in seconds at which the job completed; null until then. |
| expires_at | integer | null | Unix time in seconds after which the output expires; null because outputs currently have no expiry. |
| seconds | string | Length of the video in seconds, as a string; for a completed job it is the delivered length. |
| size | string | Resolution of the video as `WIDTHxHEIGHT`; null when the provider did not report one. |
| prompt | string | null | Prompt the job was created with. |
| remixed_from_video_id | null | Always null; remix is not supported. |
| error | object | null | Why the job failed; null unless status is `failed`. |
| error.code | string | Machine-readable failure code. |
| error.message | string | Human-readable failure message. |
| polling_url | string | Relative URL to poll for the job state; same as retrieveVideo for this job. |
| unsigned_urls | array<string> | Relative URLs of the finished output; empty until the video is ready. Download them with the same API key. |
| usage | object | Cost of the job; present once a price applies. |
| usage.cost | number | Cost of the job in USD: delivered seconds times the per-second price once completed, 0 while running. |
# 下载视频内容
先调用「创建视频」，用返回的 ID 替换 video\_123；下载前须轮询至 completed。
## 响应 [#响应]
### HTTP 200 [#http-200]
Video or thumbnail bytes
**video/mp4**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string (binary) | |
**image/jpeg**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string (binary) | |
# 删除视频
先调用「创建视频」，用返回的 ID 替换 video\_123；下载前须轮询至 completed。
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id of the deleted video job. |
| object | string | Object type; always `video.deleted`. |
| deleted | boolean | Always true; the job is no longer readable. |
#
先调用「创建视频」，用返回的 ID 替换 video\_123；下载前须轮询至 completed。
## 响应 [#响应]
此端点没有声明成功响应。
# 转写音频
## 响应 [#响应]
### HTTP 200 [#http-200]
Transcription in the requested format.
**text/plain**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string | |
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| text | string | |
| task | string | |
| language | string | |
| duration | number | |
| segments | array<object> | |
| segments[].id | integer | |
| segments[].start | number | |
| segments[].end | number | |
| segments[].text | string | |
| segments[].temperature | number | |
| segments[].avg_logprob | number | |
| segments[].compression_ratio | number | |
| segments[].no_speech_prob | number | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
OK
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | The file identifier, which can be referenced in the API endpoints. |
| bytes | integer | The size of the file, in bytes. |
| created_at | integer | The Unix timestamp (in seconds) for when the file was created. |
| expires_at | integer | The Unix timestamp (in seconds) for when the file will expire. |
| filename | string | The name of the file. |
| object | string | The object type, which is always `file`. |
| purpose | string | The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`. |
| status | string | Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`. |
| status_details | string | Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. |
# 列出文件
## 响应 [#响应]
### HTTP 200 [#http-200]
OK
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| object | string | |
| data | array<object> | |
| data[].id | string | The file identifier, which can be referenced in the API endpoints. |
| data[].bytes | integer | The size of the file, in bytes. |
| data[].created_at | integer | The Unix timestamp (in seconds) for when the file was created. |
| data[].expires_at | integer | The Unix timestamp (in seconds) for when the file will expire. |
| data[].filename | string | The name of the file. |
| data[].object | string | The object type, which is always `file`. |
| data[].purpose | string | The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`. |
| data[].status | string | Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`. |
| data[].status_details | string | Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. |
| first_id | string | |
| last_id | string | |
| has_more | boolean | |
# 检索文件
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
OK
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | The file identifier, which can be referenced in the API endpoints. |
| bytes | integer | The size of the file, in bytes. |
| created_at | integer | The Unix timestamp (in seconds) for when the file was created. |
| expires_at | integer | The Unix timestamp (in seconds) for when the file will expire. |
| filename | string | The name of the file. |
| object | string | The object type, which is always `file`. |
| purpose | string | The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`. |
| status | string | Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`. |
| status_details | string | Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. |
# 删除文件
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
OK
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| object | string | |
| deleted | boolean | |
# 检索文件内容
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
OK
**application/octet-stream**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string (binary) | |
# 知识库
官方 openai Python SDK 可直接使用知识库、文件和批次操作。两个地址访问同一份数据。
`https://api.deepraxis.ai/openai/v1`
[快速开始：官方 Python SDK](/docs/cloud/services/knowledge/quickstart)
## 当前差异 [#当前差异]
搜索按块返回，同一文件可能出现多次；max\_num\_results 计算块数。rewrite\_query 为 true 时先用小模型改写查询（按模型用量计费，失败时回退原查询），改写所用模型只能在原生 API 的 models 中设置，兼容接口传 models 返回 400。搜索 has\_more 恒为 false、next\_page 恒为 null。description 接受后丢弃。expand=files 与 expand\[]=files 为 Praxis 扩展；未知值忽略。
删除知识库后保留 7 天，读取仍可返回 200 completed，但写入和搜索返回 409。恢复、失败重试、分段、事件和混合搜索权重请使用原生 API；兼容接口不返回 praxis、chunk\_id、page 或 span。usage\_bytes 为抽取文本块的字节数。未知请求字段当前会被忽略。
[原生 API](/docs/api/native/knowledge) · [错误码](/docs/api/native/knowledge/errors)
| 方法 | 路径 | 操作 |
| ------ | -------------------------------------------------------------------------------- | ------ |
| POST | /openai/v1/vector\_stores | 创建知识库 |
| GET | /openai/v1/vector\_stores | 列出知识库 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id} | 读取知识库 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id} | 更新知识库 |
| DELETE | /openai/v1/vector\_stores/\{vector\_store\_id} | 删除知识库 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id}/search | 搜索知识库 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id}/files | 添加文件 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id}/files | 列出文件 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id} | 读取文件 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id} | 更新文件属性 |
| DELETE | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id} | 移除文件 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id}/content | 读取抽取内容 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches | 创建文件批次 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id} | 读取文件批次 |
| POST | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id}/cancel | 取消文件批次 |
| GET | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id}/files | 列出批次文件 |
## 创建知识库 [#创建知识库]
`POST /openai/v1/vector_stores`
创建知识库。可用 file\_ids 添加已有 File 并异步入库；后续调用使用返回的 id。最小请求体：\{"name":"Refund policies"}。
### 请求体 [#请求体]
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | string | 可选; 省略时为空字符串；不接受 null。; 最长字符数: 256; 默认: "" |
| metadata | object / null | 可选; 知识库自定义字符串元数据；省略或 null 得到空对象。; 默认: {} |
| expires_after | object / null | 可选; 从最近活动计算的过期策略；省略或 null 表示不自动过期。; 默认: null |
| expires_after (1).anchor | "last_active_at" | 必填; last_active_at 表示从最近活动时间开始计算过期。 |
| expires_after (1).days | integer | 必填; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
| file_ids | string[] | 可选; 要加入的已有文件 ID；每库最多 10,000 个文件。 |
| chunking_strategy | object / object | 可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"} |
| chunking_strategy (1).type | "auto" | 必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。 |
| chunking_strategy (2).type | "static" | 必填; static 表示使用显式分段大小与重叠设置。 |
| chunking_strategy (2).static | object | 必填; 以估算 token 数表示的分段大小与重叠限制。 |
| chunking_strategy (2).static.max_chunk_size_tokens | integer | 必填; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| chunking_strategy (2).static.chunk_overlap_tokens | integer | 必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| description | string | 可选; 不生效: 接受后丢弃，不保存也不返回；当前不校验类型。 |
### 请求示例 [#请求示例]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Refund policies\"}"
```
### 响应 [#响应]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store" | 必有; 对象标记；vector_store 表示知识库。 |
| name | string | 必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256 |
| status | "in_progress" / "completed" / "expired" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| usage_bytes | integer | 必有; 已完成源文件的字节数之和。; 最小: 0 |
| file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
| last_active_at | integer / null | 必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。 |
| expires_after | object / null | 必有; 从最近活动开始计算的过期策略；null 表示不自动过期。 |
| expires_after (1).anchor | "last_active_at" | 必有; last_active_at 表示从最近活动时间开始计算过期。 |
| expires_after (1).days | integer | 必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
| expires_at | integer / null | 必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。 |
| metadata | object | 必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 列出知识库 [#列出知识库]
`GET /openai/v1/vector_stores`
列出调用方可见的知识库，默认最新在前。将 last\_id 作为 after 读取下一页，例如 ?limit=20。
### 参数 [#参数]
| 名称 | 位置与类型 | 说明 |
| ------ | --------------------- | ------------------------------------- |
| after | query: string | 上一页的 ID 游标。 最短字符数: 1 |
| before | query: string | 返回此 ID 之前的条目。 最短字符数: 1 |
| limit | query: integer | 每页条数。 最小: 1; 最大: 100; 默认: 20 |
| order | query: "asc" / "desc" | 知识库和文件默认按创建时间降序；分段默认按序号升序。 默认: "desc" |
### 请求示例 [#请求示例-1]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-1]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "list" | 必有; 对象标记；list 表示游标分页集合。 |
| data | object[] | 必有; 按请求顺序返回的当前页条目。 |
| data[].id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].object | "vector_store" | 必有; 对象标记；vector_store 表示知识库。 |
| data[].name | string | 必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256 |
| data[].status | "in_progress" / "completed" / "expired" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| data[].usage_bytes | integer | 必有; 已完成源文件的字节数之和。; 最小: 0 |
| data[].file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| data[].file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| data[].file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| data[].file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| data[].file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| data[].file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| data[].created_at | integer | 必有; Unix 时间戳，单位秒。 |
| data[].last_active_at | integer / null | 必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。 |
| data[].expires_after | object / null | 必有; 从最近活动开始计算的过期策略；null 表示不自动过期。 |
| data[].expires_after (1).anchor | "last_active_at" | 必有; last_active_at 表示从最近活动时间开始计算过期。 |
| data[].expires_after (1).days | integer | 必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
| data[].expires_at | integer / null | 必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。 |
| data[].metadata | object | 必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 读取知识库 [#读取知识库]
`GET /openai/v1/vector_stores/{vector_store_id}`
使用创建或列表返回的 id 读取知识库。添加 ?expand=files 可同时返回附件首页。已删除的库返回 404。
### 参数 [#参数-1]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ----------------- | -------------------------------------- |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| expand | query: "files"\[] | 两个地址均支持的 Praxis 扩展：files 附带文件首页；未知值忽略。 |
| expand\[] | query: "files"\[] | 两个地址均支持的 Praxis 扩展：files 附带文件首页；未知值忽略。 |
### 请求示例 [#请求示例-2]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-2]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| (1).id | string | 必有; 资源 ID。; 最短字符数: 1 |
| (1).object | "vector_store" | 必有; 对象标记；vector_store 表示知识库。 |
| (1).name | string | 必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256 |
| (1).status | "in_progress" / "completed" / "expired" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| (1).usage_bytes | integer | 必有; 已完成源文件的字节数之和。; 最小: 0 |
| (1).file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| (1).file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| (1).file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| (1).file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| (1).file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| (1).file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| (1).created_at | integer | 必有; Unix 时间戳，单位秒。 |
| (1).last_active_at | integer / null | 必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。 |
| (1).expires_after | object / null | 必有; 从最近活动开始计算的过期策略；null 表示不自动过期。 |
| (1).expires_after (1).anchor | "last_active_at" | 必有; last_active_at 表示从最近活动时间开始计算过期。 |
| (1).expires_after (1).days | integer | 必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
| (1).expires_at | integer / null | 必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。 |
| (1).metadata | object | 必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string |
| (2).files | object | 可选; 仅在 expand=files 时返回文件首页。 |
| (2).files.object | "list" | 必有; 对象标记；list 表示游标分页集合。 |
| (2).files.data | object[] | 必有; 按请求顺序返回的当前页条目。 |
| (2).files.data[].id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| (2).files.data[].object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| (2).files.data[].vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| (2).files.data[].status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| (2).files.data[].last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| (2).files.data[].last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| (2).files.data[].last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| (2).files.data[].usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| (2).files.data[].created_at | integer | 必有; Unix 时间戳，单位秒。 |
| (2).files.data[].chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| (2).files.data[].chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| (2).files.data[].chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| (2).files.data[].chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| (2).files.data[].chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| (2).files.data[].chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| (2).files.data[].attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
| (2).files.first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| (2).files.last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| (2).files.has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 更新知识库 [#更新知识库]
`POST /openai/v1/vector_stores/{vector_store_id}`
使用返回的 id 修改活跃知识库。省略的字段不变；metadata 替换整个对象。请求体示例：\{"name":"Refund policies"}。
### 参数 [#参数-2]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
### 请求体 [#请求体-1]
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | string / null | 可选; null 将名称清空为空字符串；省略的字段不变。 |
| metadata | object / null | 可选; 替换全部元数据；null 清空为一个空对象。 |
| expires_after | object / null | 可选; null 取消自动过期。 |
| expires_after (1).anchor | "last_active_at" | 必填; last_active_at 表示从最近活动时间开始计算过期。 |
| expires_after (1).days | integer | 必填; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
### 请求示例 [#请求示例-3]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Support policies\"}"
```
### 响应 [#响应-3]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store" | 必有; 对象标记；vector_store 表示知识库。 |
| name | string | 必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256 |
| status | "in_progress" / "completed" / "expired" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| usage_bytes | integer | 必有; 已完成源文件的字节数之和。; 最小: 0 |
| file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
| last_active_at | integer / null | 必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。 |
| expires_after | object / null | 必有; 从最近活动开始计算的过期策略；null 表示不自动过期。 |
| expires_after (1).anchor | "last_active_at" | 必有; last_active_at 表示从最近活动时间开始计算过期。 |
| expires_after (1).days | integer | 必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365 |
| expires_at | integer / null | 必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。 |
| metadata | object | 必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 删除知识库 [#删除知识库]
`DELETE /openai/v1/vector_stores/{vector_store_id}`
删除后读取和重复 DELETE 返回 404 not\_found\_error，列表不含已删除库；自有面可在 7 天内恢复。
### 参数 [#参数-3]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
### 请求示例 [#请求示例-4]
```bash
curl -X DELETE "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-4]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.deleted" | 必有; 对象标记；vector_store.deleted 表示此操作回执。 |
| deleted | true | 必有; 确认兼容面的知识库删除；后续访问返回未找到。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 搜索知识库 [#搜索知识库]
`POST /openai/v1/vector_stores/{vector_store_id}/search`
每文件一条，content 为按分数降序的命中块；max\_num\_results 计文件，从最多 50 个召回分段聚合。has\_more 表示文件结果截断，next\_page 仍为 null。
### 参数 [#参数-4]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
### 请求体 [#请求体-2]
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| query | string / string[] | 必填; 非空白文本；多个查询以换行连接后共同搜索。 |
| filters | object / object / object | 可选; 按类型严格匹配文件属性；根条件以下最多嵌套 20 层。 |
| filters (1).type | "eq" / "ne" / "gt" / "gte" / "lt" / "lte" | 必填; eq 等于，ne 不等于，gt 大于，gte 大于等于，lt 小于，lte 小于等于；属性必须存在且值类型一致。 |
| filters (1).key | string | 必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1 |
| filters (1).value | string / number / boolean | 必填; 不进行类型转换的比较值。 |
| filters (2).type | "in" / "nin" | 必填; in 匹配数组中的值；nin 匹配不在数组中的值。属性不存在时均不匹配。 |
| filters (2).key | string | 必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1 |
| filters (2).value | string / number[] | 必填; 不进行类型转换的字符串或数值成员列表。 |
| filters (3).type | "and" / "or" | 必填; and 要求所有子条件匹配；or 要求至少一个子条件匹配。 |
| filters (3).filters | object / object / object[] | 必填; 按选定 and/or 运算符组合的非空子条件列表。; 最少条数: 1 |
| filters (3).filters[] | object / object / object | 递归使用同一筛选结构，嵌套上限 20 层。 |
| max_num_results | integer | 可选; 从最多 50 个召回分段聚合后，最多返回的不同文件数。; 最小: 1; 最大: 50; 默认: 10 |
| rewrite_query | boolean | 可选; 支持: 为 true 时，先用该库 query_rewrite 角色的模型把每条查询改写为简洁的检索查询；检索使用改写结果，search_query 返回改写后的查询。每次改写是一次小模型调用，按模型用量计费。改写失败、超时（5 秒）或为空时，该条查询回退为原文，搜索照常完成。省略或为 false 时不调用模型。 |
| next_page | string | 可选; 不生效: 搜索不支持翻页；提供游标不生效。 |
| ranking_options | object | 可选; 控制结果排序与纳入结果的最低分数。 |
| ranking_options.ranker | "none" / "auto" / "default-2024-11-15" | 可选; 只有 default-2024-11-15 请求重排；none、auto 和省略时使用初始排序。尚未单独实测重排效果。 |
| ranking_options.score_threshold | number | 可选; 最低分数；分数不是相关性概率。尚未单独实测阈值效果。; 最小: 0; 最大: 1; 默认: 0 |
| ranking_options.hybrid_search | object | 可选; 不支持: 在 /openai/v1 返回 400 INVALID_PARAMS；设置权重请使用 /knowledge/v1。; Praxis 扩展 |
| ranking_options.hybrid_search.embedding_weight | number | 必填; 语义检索相对权重；零表示禁用语义检索。; 最小: 0; 默认: 0.7 |
| ranking_options.hybrid_search.text_weight | number | 必填; 关键词检索相对权重；零表示禁用关键词检索。; 最小: 0; 默认: 0.3 |
| praxis | object | 可选; 不生效: 兼容响应会删除 praxis，包括搜索解释。 |
| praxis.explain | boolean | 可选; 请求生成解释；兼容响应不返回这些解释。 |
### 请求示例 [#请求示例-5]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/search" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"query\":\"When will I receive my refund?\",\"max_num_results\":5}"
```
### 响应 [#响应-5]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "vector_store.search_results.page" | 必有; 对象标记；vector_store.search_results.page 表示搜索结果页。 |
| search_query | string[] | 必有; 实际用于检索的查询，与输入一一对应；rewrite_query 为 true 时为改写后的查询，否则原样返回。 |
| data | object[] | 必有; 每个文件返回一条；content 包含该文件命中的分段。 |
| data[].file_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].filename | string | 必有; 命中文件的源文件名。 |
| data[].score | number | 必有; 该文件命中分段的最高分数。; 最小: 0; 最大: 1 |
| data[].attributes | object / null | 必有; 用于筛选的当前文件属性；未设置时为 null。 |
| data[].content | object[] | 必有; 按分段分数降序排列的命中分段。 |
| data[].content[].type | "text" | 必有; text 表示提取出的文本分段。 |
| data[].content[].text | string | 必有; 命中分段的提取文本，可能与相邻分段重叠。 |
| has_more | boolean | 必有; 过滤后的文件数超过 max_num_results 时为 true；next_page 仍为 null。; 支持: |
| next_page | null | 必有; 不生效: 恒为 null，没有下一页搜索结果。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 添加文件 [#添加文件]
`POST /openai/v1/vector_stores/{vector_store_id}/files`
异步处理。重复加入同一文件返回已有记录，不应用新的属性或分段策略。
### 参数 [#参数-5]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
### 请求体 [#请求体-3]
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| file_id | string | 必填; 上传文件返回的已有源 File ID；文件必须对调用方可见。; 最短字符数: 1 |
| attributes | object / null | 可选; 新附件的搜索筛选属性；省略或 null 表示不设置。重复加入已有文件不改变属性。 |
| chunking_strategy | object / object | 可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"} |
| chunking_strategy (1).type | "auto" | 必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。 |
| chunking_strategy (2).type | "static" | 必填; static 表示使用显式分段大小与重叠设置。 |
| chunking_strategy (2).static | object | 必填; 以估算 token 数表示的分段大小与重叠限制。 |
| chunking_strategy (2).static.max_chunk_size_tokens | integer | 必填; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| chunking_strategy (2).static.chunk_overlap_tokens | integer | 必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
### 请求示例 [#请求示例-6]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"file_id\":\"${FILE_ID}\"}"
```
### 响应 [#响应-6]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
| chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 列出文件 [#列出文件]
`GET /openai/v1/vector_stores/{vector_store_id}/files`
列出附件及入库状态，默认最新附件在前。使用 last\_id 作为 after 继续查询；?filter=failed 筛选可重新入库的失败文件。
### 参数 [#参数-6]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| after | query: string | 上一页的 ID 游标。 最短字符数: 1 |
| before | query: string | 返回此 ID 之前的条目。 最短字符数: 1 |
| limit | query: integer | 每页条数。 最小: 1; 最大: 100; 默认: 20 |
| order | query: "asc" / "desc" | 知识库和文件默认按创建时间降序；分段默认按序号升序。 默认: "desc" |
| filter | query: "in\_progress" / "completed" / "failed" / "cancelled" | in\_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。省略时包含全部状态。 |
### 请求示例 [#请求示例-7]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-7]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "list" | 必有; 对象标记；list 表示游标分页集合。 |
| data | object[] | 必有; 按请求顺序返回的当前页条目。 |
| data[].id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| data[].object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| data[].vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| data[].last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| data[].last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| data[].last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| data[].usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| data[].created_at | integer | 必有; Unix 时间戳，单位秒。 |
| data[].chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| data[].chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| data[].chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| data[].chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| data[].chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| data[].chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| data[].attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 读取文件 [#读取文件]
`GET /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`
使用添加附件或附件列表返回的 id 读取文件。可轮询此操作，直到 status 离开 in\_progress 后确认入库结果。
### 参数 [#参数-7]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| file\_id | path: string | 必填；添加附件或附件列表返回的源 File ID。 最短字符数: 1 |
### 请求示例 [#请求示例-8]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-8]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
| chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 更新文件属性 [#更新文件属性]
`POST /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`
替换已有附件的搜索筛选属性，不重新入库。使用附件 id。请求体示例：\{"attributes":\{"category":"refund"}}；null 清空属性。
### 参数 [#参数-8]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| file\_id | path: string | 必填；添加附件或附件列表返回的源 File ID。 最短字符数: 1 |
### 请求体 [#请求体-4]
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| attributes | object / null | 可选; 替换全部搜索筛选属性；null 清空属性。 |
### 请求示例 [#请求示例-9]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"attributes\":{\"category\":\"refund\"}}"
```
### 响应 [#响应-9]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
| chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 移除文件 [#移除文件]
`DELETE /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`
返回后立即不再搜索到该文件；不会删除源文件。
### 参数 [#参数-9]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| file\_id | path: string | 必填；添加附件或附件列表返回的源 File ID。 最短字符数: 1 |
### 请求示例 [#请求示例-10]
```bash
curl -X DELETE "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-10]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.file.deleted" | 必有; 对象标记；vector_store.file.deleted 表示此操作回执。 |
| deleted | true | 必有; 确认已从此知识库移出；源 File 未删除。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 读取抽取内容 [#读取抽取内容]
`GET /openai/v1/vector_stores/{vector_store_id}/files/{file_id}/content`
抽取文本按分段返回，可能重叠。图片内容可能是生成的描述，并非逐字 OCR。
### 参数 [#参数-10]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| file\_id | path: string | 必填；添加附件或附件列表返回的源 File ID。 最短字符数: 1 |
### 请求示例 [#请求示例-11]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}/content" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-11]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "vector_store.file_content.page" | 必有; 对象标记；vector_store.file_content.page 表示提取的文件内容。 |
| data | object[] | 必有; 按分段序号排列的全部现存文本分段；相邻分段可能重叠。 |
| data[].type | "text" | 必有; text 表示提取出的文本分段。 |
| data[].text | string | 必有; 此分段的提取文本；可能与相邻分段重叠。 |
| has_more | false | 必有; 恒为 false；此响应返回全部现存分段。 |
| next_page | null | 必有; 恒为 null；提取内容不分页。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 创建文件批次 [#创建文件批次]
`POST /openai/v1/vector_stores/{vector_store_id}/file_batches`
批量添加已有 File 并异步入库。file\_ids 与 files 必须且只能提供一个；files 支持逐文件设置。已有附件直接复用。使用返回的批次 id 查询进度。
### 参数 [#参数-11]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
### 请求体 [#请求体-5]
file\_ids 与 files 必须且只能提供一个。已有文件直接复用，不修改属性或分段策略。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| (1).file_ids | string[] | 必填; 使用共同属性和分段设置的已有 File ID 列表。file_ids 与 files 二选一。; 最少条数: 1; 最多条数: 500 |
| (1).attributes | object / null | 可选; 用于每个新附件的搜索筛选属性；省略或 null 表示不设置。 |
| (1).chunking_strategy | object / object | 可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"} |
| (1).chunking_strategy (1).type | "auto" | 必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。 |
| (1).chunking_strategy (2).type | "static" | 必填; static 表示使用显式分段大小与重叠设置。 |
| (1).chunking_strategy (2).static | object | 必填; 以估算 token 数表示的分段大小与重叠限制。 |
| (1).chunking_strategy (2).static.max_chunk_size_tokens | integer | 必填; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| (1).chunking_strategy (2).static.chunk_overlap_tokens | integer | 必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| (2).files | object[] | 必填; 分别指定属性和分段设置的附件列表；忽略顶层 attributes 与 chunking_strategy。; 最少条数: 1; 最多条数: 500 |
| (2).files[].file_id | string | 必填; 上传文件返回的已有源 File ID；文件必须对调用方可见。; 最短字符数: 1 |
| (2).files[].attributes | object | 可选; 用于搜索筛选的文件属性。最多 16 个键，键最多 64 字符，字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string / number / boolean |
| (2).files[].chunking_strategy | object / object | 可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"} |
| (2).files[].chunking_strategy (1).type | "auto" | 必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。 |
| (2).files[].chunking_strategy (2).type | "static" | 必填; static 表示使用显式分段大小与重叠设置。 |
| (2).files[].chunking_strategy (2).static | object | 必填; 以估算 token 数表示的分段大小与重叠限制。 |
| (2).files[].chunking_strategy (2).static.max_chunk_size_tokens | integer | 必填; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| (2).files[].chunking_strategy (2).static.chunk_overlap_tokens | integer | 必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| (2).attributes | JSON | 可选; 不生效: 使用 files 时不生效。 |
| (2).chunking_strategy | JSON | 可选; 不生效: 使用 files 时不生效。 |
### 请求示例 [#请求示例-12]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/file_batches" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"file_ids\":[\"${FILE_ID}\"]}"
```
### 响应 [#响应-12]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.files_batch" | 必有; 对象标记；vector_store.files_batch 表示批量附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。 |
| file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 读取文件批次 [#读取文件批次]
`GET /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}`
读取此知识库中创建的批次，包括当前状态和文件计数。使用创建批次返回的 id 监测入库结果。
### 参数 [#参数-12]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| batch\_id | path: string | 必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1 |
### 请求示例 [#请求示例-13]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-13]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.files_batch" | 必有; 对象标记；vector_store.files_batch 表示批量附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。 |
| file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 取消文件批次 [#取消文件批次]
`POST /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`
只取消处理中的批次和文件。已完成、失败或已取消的批次原样返回（200，幂等），计数不变。
### 参数 [#参数-13]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| batch\_id | path: string | 必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1 |
### 请求示例 [#请求示例-14]
```bash
curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}/cancel" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-14]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.files_batch" | 必有; 对象标记；vector_store.files_batch 表示批量附件。 |
| vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。 |
| file_counts | object | 必有; 仍属于该库或批次的附件数量，按入库状态分组。 |
| file_counts.in_progress | integer | 必有; 等待或正在入库的文件数。; 最小: 0 |
| file_counts.completed | integer | 必有; 已完成入库的文件数。; 最小: 0 |
| file_counts.failed | integer | 必有; 入库失败的文件数。; 最小: 0 |
| file_counts.cancelled | integer | 必有; 因批次取消而停止入库的文件数。; 最小: 0 |
| file_counts.total | integer | 必有; 全部入库状态的附件总数。; 最小: 0 |
| created_at | integer | 必有; Unix 时间戳，单位秒。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
## 列出批次文件 [#列出批次文件]
`GET /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`
列出指定批次仍在库中的附件，默认最新附件在前。使用批次创建返回的 id；?filter=failed 查看失败文件，last\_id 可作为下一页 after。
### 参数 [#参数-14]
| 名称 | 位置与类型 | 说明 |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |
| batch\_id | path: string | 必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1 |
| after | query: string | 上一页的 ID 游标。 最短字符数: 1 |
| before | query: string | 返回此 ID 之前的条目。 最短字符数: 1 |
| limit | query: integer | 每页条数。 最小: 1; 最大: 100; 默认: 20 |
| order | query: "asc" / "desc" | 知识库和文件默认按创建时间降序；分段默认按序号升序。 默认: "desc" |
| filter | query: "in\_progress" / "completed" / "failed" / "cancelled" | in\_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。省略时包含全部状态。 |
### 请求示例 [#请求示例-15]
```bash
curl -X GET "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}/files" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
### 响应 [#响应-15]
HTTP 200
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "list" | 必有; 对象标记；list 表示游标分页集合。 |
| data | object[] | 必有; 按请求顺序返回的当前页条目。 |
| data[].id | string | 必有; 与源文件相同的 ID。; 最短字符数: 1 |
| data[].object | "vector_store.file" | 必有; 对象标记；vector_store.file 表示知识库中的附件。 |
| data[].vector_store_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].status | "in_progress" / "completed" / "cancelled" / "failed" | 必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。 |
| data[].last_error | object / null | 必有; 入库失败详情；未失败、成功完成或重新入库时为 null。 |
| data[].last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | 必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。 |
| data[].last_error (1).message | string | 必有; 与 code 对应的入库失败说明。 |
| data[].usage_bytes | integer | 必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0 |
| data[].created_at | integer | 必有; Unix 时间戳，单位秒。 |
| data[].chunking_strategy | object / object | 必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。 |
| data[].chunking_strategy (1).type | "static" | 必有; static 表示使用显式分段大小与重叠设置。 |
| data[].chunking_strategy (1).static | object | 必有; 以估算 token 数表示的分段大小与重叠限制。 |
| data[].chunking_strategy (1).static.max_chunk_size_tokens | integer | 必有; 每段的估算 token 数。; 最小: 100; 最大: 4096 |
| data[].chunking_strategy (1).static.chunk_overlap_tokens | integer | 必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048 |
| data[].chunking_strategy (2).type | "other" | 必有; other identifies a stored strategy whose chunk-size settings are unavailable. |
| data[].attributes | object / null | 必有; 用于搜索筛选的文件属性；null 表示未设置。 |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |
[错误码与错误对象](/docs/api/native/knowledge/errors)
# Anthropic 兼容接口
## 基础地址 [#基础地址]
## 接入 [#接入]
## 端点 [#端点]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ---------------------------------------------------------------------------- | -------- | ------ |
| POST | [`/v1/messages`](/docs/api/compatible/anthropic/createMessage) | 发送消息 | ● 支持 |
| POST | [`/v1/messages/count_tokens`](/docs/api/compatible/anthropic/countTokens) | 统计 token | ◐ 部分支持 |
| GET | [`/v1/models`](/docs/api/compatible/anthropic/listModels) | 列出模型 | ● 支持 |
| POST | [`/v1/files`](/docs/api/compatible/anthropic/createFile) | 上传文件 | ● 支持 |
| GET | [`/v1/files`](/docs/api/compatible/anthropic/listFiles) | 列出文件 | ● 支持 |
| GET | [`/v1/files/{file_id}`](/docs/api/compatible/anthropic/retrieveFile) | 读取文件信息 | ● 支持 |
| DELETE | [`/v1/files/{file_id}`](/docs/api/compatible/anthropic/deleteFile) | 删除文件 | ● 支持 |
| GET | [`/v1/files/{file_id}/content`](/docs/api/compatible/anthropic/downloadFile) | 下载文件内容 | ● 支持 |
## 与官方的差异 [#与官方的差异]
* 发送消息：支持顶层 cache\_control、top\_k、metadata.user\_id、output\_config.format、thinking.display 与 anthropic-user-profile-id。仅原生 Anthropic 能表达的选项会限制路由；没有可保真供应时返回参数错误。anthropic-workspace-id 尚未支持，非空值返回 400。container、inference\_geo 与 service\_tier 接受并忽略；其他扩展见字段支持标注。 未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* 统计 token：按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。
* 列出模型：始终返回 capabilities、max\_input\_tokens、max\_tokens；目录无法确定的值为 null，不将总上下文窗口冒充独立输入上限。非空 anthropic-workspace-id 返回 400；尚不按 anthropic-beta 选择目录版本。
* 上传文件：SDK 0.128.0 上传参数为表单 file 和可选的表单 expires\_in\_seconds（3600–7776000 秒）。其他表单字段（包括 purpose）返回 400 invalid\_request\_error，消息形如 "purpose: Extra inputs are not permitted"；查询参数只接受 SDK 自带的 beta，其他查询参数返回 400，查询参数 expires\_in\_seconds 会提示改放表单。平台将上传文件记为 user\_data；不支持 anthropic-workspace-id，请求携带该头时返回 400。
* 列出文件：按创建时间从新到旧排列。用 after\_id / before\_id 与 limit 分页（两者同时给返回 400），也可以用 page 游标（next\_page）；三者只能选一个。响应包含 data、has\_more、first\_id、last\_id 与 next\_page。ids（最多 100 个去重 ID）与 page、after\_id、before\_id、limit 互斥。scope\_id 需要 anthropic-beta: managed-agents-2026-04-01 请求头；缺少该头返回 400，不存在的会话范围返回 404。anthropic-workspace-id 返回 400。
* 下载文件内容：只有代码执行工具生成的文件可以下载；你自己上传的文件（用途为 user\_data）下载会返回 400 invalid\_request\_error，这与 Anthropic 官方的行为一致。
参数与字段的权威定义以 [Anthropic 官方文档](https://docs.anthropic.com/en/api)为准。
错误按 Anthropic 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
# 发送消息
## 响应 [#响应]
### HTTP 200 [#http-200]
Message created
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique object identifier. The format and length of IDs may change over time. |
| container | null | object | Information about the container used in the request (for the code execution tool) |
| container.id | string | Identifier for the container used in this request |
| container.expires_at | string | The time at which the container will expire. |
| container.skills | null | array<object> | Skills loaded in the container |
| content | array<object> | Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{ "type": "text", "text": "Hi, I'm Claude." }] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Then the response `content` might be: ```json [{ "type": "text", "text": "B)" }] ``` |
| content[].citations | null | array<object> | Citations supporting the text block. The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. |
| content[].text | string | The text generated by the model. |
| content[].type | string | Always `text`. Discriminator that marks this object as a TextBlock in a `type`-tagged union. / Always `thinking`. Discriminator that marks this object as a ThinkingBlock in a `type`-tagged union. / Always `redacted_thinking`. Discriminator that marks this object as a RedactedThinkingBlock in a `type`-tagged union. / Always `tool_use`. Discriminator that marks this object as a ToolUseBlock in a `type`-tagged union. / Always `server_tool_use`. Discriminator that marks this object as a ServerToolUseBlock in a `type`-tagged union. / Always `web_search_tool_result`. Discriminator that marks this object as a WebSearchToolResultBlock in a `type`-tagged union. / Always `web_fetch_tool_result`. Discriminator that marks this object as a WebFetchToolResultBlock in a `type`-tagged union. / Always `code_execution_tool_result`. Discriminator that marks this object as a CodeExecutionToolResultBlock in a `type`-tagged union. / Always `bash_code_execution_tool_result`. Discriminator that marks this object as a BashCodeExecutionToolResultBlock in a `type`-tagged union. / Always `text_editor_code_execution_tool_result`. Discriminator that marks this object as a TextEditorCodeExecutionToolResultBlock in a `type`-tagged union. / Always `tool_search_tool_result`. Discriminator that marks this object as a ToolSearchToolResultBlock in a `type`-tagged union. / Always `container_upload`. Discriminator that marks this object as a ContainerUploadBlock in a `type`-tagged union. |
| content[].signature | string | A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details. |
| content[].thinking | string | The text of Claude's thinking process for this block. |
| content[].data | string | The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details. |
| content[].id | string | Id of the tool call; send it back as tool_use_id in the tool_result block that answers it. / Id of the server tool call; the matching result block repeats it as tool_use_id. |
| content[].caller | object | Which party invoked the tool: the model directly or a code execution tool. / Which party invoked the server tool: the model directly or a code execution tool. / Which party invoked the search: the model directly or a code execution tool. / Which party invoked the fetch: the model directly or a code execution tool. |
| content[].input | any | Arguments the model chose, as a JSON object that follows the tool's input_schema. / Arguments the model passed to the server tool, as a JSON object. |
| content[].name | string | Name of the tool the model wants to call. / Name of the server tool the model called, such as web_search, web_fetch or code_execution. |
| content[].toolset_name | null | string | For a toolset member tool_use, the toolset family. |
| content[].content | object | array<object> | object | object | object | object | object | Search results (array of web_search_result blocks) or an error object. / The fetched document or an error object. / Result of the code execution: a result block, an encrypted result block, or an error object. / Result of the bash command: a result block or an error object. / Result of the text editor command: a view, create or str_replace result block, or an error object. / Result of the tool search: a search result block that lists tool references, or an error object. |
| content[].tool_use_id | string | Id of the web_search server tool call this result belongs to. / Id of the web_fetch server tool call this result belongs to. / Id of the code_execution server tool call this result belongs to. / Id of the bash_code_execution server tool call this result belongs to. / Id of the text_editor_code_execution server tool call this result belongs to. / Id of the tool search server tool call this result belongs to. |
| content[].file_id | string | Id of the file that was uploaded into the code execution container. |
| model | string | The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| role | string | Conversational role of the generated message. This will always be `"assistant"`. |
| stop_details | null | object | Structured information about a refusal. |
| stop_details.category | null | string | The policy category that triggered a refusal. - `cyber` - The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `bio` - The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `frontier_llm` - The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. - `reasoning_extraction` - The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking). - `general_harms` - The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. |
| stop_details.explanation | null | string | Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. |
| stop_details.type | string | Always `refusal`. Discriminator that marks this object as a RefusalStopDetails in a `type`-tagged union. |
| stop_reason | null | string | The reason that we stopped. This may be one the following values: - `"end_turn"`: the model reached a natural stopping point - `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - `"tool_use"`: the model invoked one or more tools - `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - `"refusal"`: when streaming classifiers intervene to handle potential policy violations - `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. |
| stop_sequence | null | string | Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. |
| type | string | Object type. For Messages, this is always `"message"`. |
| usage | object | Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. |
| usage.cache_creation | null | object | Breakdown of cached tokens by TTL |
| usage.cache_creation_input_tokens | null | number | The number of input tokens used to create the cache entry. |
| usage.cache_read_input_tokens | null | number | The number of input tokens read from the cache. |
| usage.inference_geo | null | string | The geographic region where inference was performed for this request. |
| usage.input_tokens | number | The number of input tokens which were used. |
| usage.output_tokens | number | The number of output tokens which were used. |
| usage.output_tokens_details | null | object | Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. |
| usage.server_tool_use | null | object | The number of server tool requests. |
| usage.service_tier | null | string | If the request used the priority, standard, or batch tier. |
**text/event-stream — chunk / 事件对象**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| delta | object | Final fields of the message sent with message_delta: why generation stopped and the container. / The incremental change to the content block at index. |
| delta.container | null | object | Information about the container used in the request (for the code execution tool) |
| delta.stop_details | null | object | Structured information about a refusal. |
| delta.stop_reason | null | string | Why the model stopped; null while the message is still generating. |
| delta.stop_sequence | null | string | The custom stop sequence that was matched; null unless stop_reason is stop_sequence. |
| delta.text | string | Text fragment to append to the text block. |
| delta.type | string | Always `text_delta`. Discriminator that marks this object as a TextDelta in a `type`-tagged union. / Always `input_json_delta`. Discriminator that marks this object as a InputJSONDelta in a `type`-tagged union. / Always `citations_delta`. Discriminator that marks this object as a CitationsDelta in a `type`-tagged union. / Always `thinking_delta`. Discriminator that marks this object as a ThinkingDelta in a `type`-tagged union. / Always `signature_delta`. Discriminator that marks this object as a SignatureDelta in a `type`-tagged union. |
| delta.partial_json | string | Fragment of the tool input JSON string; concatenate all fragments of a block and parse the result when the block stops. |
| delta.citation | object | The citation to attach to the text block being streamed. |
| delta.thinking | string | The incremental `thinking` text for this content block. Concatenate the `thinking` values of successive `thinking_delta` events to assemble the block's full `thinking` value. |
| delta.signature | string | The `signature` for this thinking block: an opaque value used to verify that the block was generated by Claude when it is passed back to the API. Delivered in a `signature_delta` event just before the block's `content_block_stop` event. |
| type | string | Always `message_delta`. Discriminator that marks this object as a RawMessageDeltaEvent in a `type`-tagged union. / Always `content_block_delta`. Discriminator that marks this object as a RawContentBlockDeltaEvent in a `type`-tagged union. / Always `message_start`. Discriminator that marks this object as a RawMessageStartEvent in a `type`-tagged union. / Always `message_stop`. Discriminator that marks this object as a RawMessageStopEvent in a `type`-tagged union. / Always `content_block_start`. Discriminator that marks this object as a RawContentBlockStartEvent in a `type`-tagged union. / Always `content_block_stop`. Discriminator that marks this object as a RawContentBlockStopEvent in a `type`-tagged union. |
| usage | object | Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. |
| usage.cache_creation_input_tokens | null | number | The cumulative number of input tokens used to create the cache entry. |
| usage.cache_read_input_tokens | null | number | The cumulative number of input tokens read from the cache. |
| usage.input_tokens | null | number | The cumulative number of input tokens which were used. |
| usage.output_tokens | number | The cumulative number of output tokens which were used. |
| usage.output_tokens_details | null | object | Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. |
| usage.server_tool_use | null | object | The number of server tool requests. |
| index | number | Zero-based index of the content block this delta applies to. / Zero-based index of the content block that starts. / Zero-based index of the content block that ends. |
| message | object | The complete Message object being started; its content is empty at message_start and filled by the following content_block events. |
| message.id | string | Unique object identifier. The format and length of IDs may change over time. |
| message.container | null | object | Information about the container used in the request (for the code execution tool) |
| message.content | array<object> | Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{ "type": "text", "text": "Hi, I'm Claude." }] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Then the response `content` might be: ```json [{ "type": "text", "text": "B)" }] ``` |
| message.model | string | The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| message.role | string | Conversational role of the generated message. This will always be `"assistant"`. |
| message.stop_details | null | object | Structured information about a refusal. |
| message.stop_reason | null | string | The reason that we stopped. This may be one the following values: - `"end_turn"`: the model reached a natural stopping point - `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - `"tool_use"`: the model invoked one or more tools - `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - `"refusal"`: when streaming classifiers intervene to handle potential policy violations - `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. |
| message.stop_sequence | null | string | Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. |
| message.type | string | Object type. For Messages, this is always `"message"`. |
| message.usage | object | Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. |
| content_block | object | The content block as it starts, with empty text or input to be filled by deltas. |
| content_block.citations | null | array<object> | Citations supporting the text block. The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. |
| content_block.text | string | The text generated by the model. |
| content_block.type | string | Always `text`. Discriminator that marks this object as a TextBlock in a `type`-tagged union. / Always `thinking`. Discriminator that marks this object as a ThinkingBlock in a `type`-tagged union. / Always `redacted_thinking`. Discriminator that marks this object as a RedactedThinkingBlock in a `type`-tagged union. / Always `tool_use`. Discriminator that marks this object as a ToolUseBlock in a `type`-tagged union. / Always `server_tool_use`. Discriminator that marks this object as a ServerToolUseBlock in a `type`-tagged union. / Always `web_search_tool_result`. Discriminator that marks this object as a WebSearchToolResultBlock in a `type`-tagged union. / Always `web_fetch_tool_result`. Discriminator that marks this object as a WebFetchToolResultBlock in a `type`-tagged union. / Always `code_execution_tool_result`. Discriminator that marks this object as a CodeExecutionToolResultBlock in a `type`-tagged union. / Always `bash_code_execution_tool_result`. Discriminator that marks this object as a BashCodeExecutionToolResultBlock in a `type`-tagged union. / Always `text_editor_code_execution_tool_result`. Discriminator that marks this object as a TextEditorCodeExecutionToolResultBlock in a `type`-tagged union. / Always `tool_search_tool_result`. Discriminator that marks this object as a ToolSearchToolResultBlock in a `type`-tagged union. / Always `container_upload`. Discriminator that marks this object as a ContainerUploadBlock in a `type`-tagged union. |
| content_block.signature | string | A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details. |
| content_block.thinking | string | The text of Claude's thinking process for this block. |
| content_block.data | string | The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details. |
| content_block.id | string | Id of the tool call; send it back as tool_use_id in the tool_result block that answers it. / Id of the server tool call; the matching result block repeats it as tool_use_id. |
| content_block.caller | object | Which party invoked the tool: the model directly or a code execution tool. / Which party invoked the server tool: the model directly or a code execution tool. / Which party invoked the search: the model directly or a code execution tool. / Which party invoked the fetch: the model directly or a code execution tool. |
| content_block.input | any | Arguments the model chose, as a JSON object that follows the tool's input_schema. / Arguments the model passed to the server tool, as a JSON object. |
| content_block.name | string | Name of the tool the model wants to call. / Name of the server tool the model called, such as web_search, web_fetch or code_execution. |
| content_block.toolset_name | null | string | For a toolset member tool_use, the toolset family. |
| content_block.content | object | array<object> | object | object | object | object | object | Search results (array of web_search_result blocks) or an error object. / The fetched document or an error object. / Result of the code execution: a result block, an encrypted result block, or an error object. / Result of the bash command: a result block or an error object. / Result of the text editor command: a view, create or str_replace result block, or an error object. / Result of the tool search: a search result block that lists tool references, or an error object. |
| content_block.tool_use_id | string | Id of the web_search server tool call this result belongs to. / Id of the web_fetch server tool call this result belongs to. / Id of the code_execution server tool call this result belongs to. / Id of the bash_code_execution server tool call this result belongs to. / Id of the text_editor_code_execution server tool call this result belongs to. / Id of the tool search server tool call this result belongs to. |
| content_block.file_id | string | Id of the file that was uploaded into the code execution container. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Token count
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input_tokens | number | The total number of tokens across the provided list of messages, system prompt, and tools. |
# 列出模型
## 响应 [#响应]
### HTTP 200 [#http-200]
Models listed
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique model identifier. |
| data[].capabilities | null | object | Model capability information. |
| data[].created_at | string | RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. |
| data[].display_name | string | A human-readable name for the model. |
| data[].max_input_tokens | null | number | Maximum input context window size in tokens for this model. |
| data[].max_tokens | null | number | Maximum value for the `max_tokens` parameter when using this model. |
| data[].type | string | Object type. For Models, this is always `"model"`. |
| has_more | boolean | |
| first_id | null | string | |
| last_id | null | string | |
# 上传文件
## 响应 [#响应]
### HTTP 200 [#http-200]
File uploaded
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique object identifier. The format and length of IDs may change over time. |
| created_at | string | RFC 3339 datetime string representing when the file was created. |
| filename | string | Original filename of the uploaded file. |
| mime_type | string | MIME type of the file. |
| size_bytes | number | Size of the file in bytes. |
| type | string | Object type. For files, this is always `"file"`. |
| downloadable | boolean | Whether the file can be downloaded. |
| expires_at | null | string | RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. |
| scope | null | object | The scope of this file, indicating the context in which it was created (e.g., a session). |
| scope.id | string | The ID of the scoping resource (e.g., the session ID). |
| scope.type | string | The type of scope (e.g., `"session"`). |
# 列出文件
## 响应 [#响应]
### HTTP 200 [#http-200]
Files listed
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique object identifier. The format and length of IDs may change over time. |
| data[].created_at | string | RFC 3339 datetime string representing when the file was created. |
| data[].filename | string | Original filename of the uploaded file. |
| data[].mime_type | string | MIME type of the file. |
| data[].size_bytes | number | Size of the file in bytes. |
| data[].type | string | Object type. For files, this is always `"file"`. |
| data[].downloadable | boolean | Whether the file can be downloaded. |
| data[].expires_at | null | string | RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. |
| data[].scope | null | object | The scope of this file, indicating the context in which it was created (e.g., a session). |
| next_page | null | string | |
# 读取文件信息
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Metadata
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique object identifier. The format and length of IDs may change over time. |
| created_at | string | RFC 3339 datetime string representing when the file was created. |
| filename | string | Original filename of the uploaded file. |
| mime_type | string | MIME type of the file. |
| size_bytes | number | Size of the file in bytes. |
| type | string | Object type. For files, this is always `"file"`. |
| downloadable | boolean | Whether the file can be downloaded. |
| expires_at | null | string | RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. |
| scope | null | object | The scope of this file, indicating the context in which it was created (e.g., a session). |
| scope.id | string | The ID of the scoping resource (e.g., the session ID). |
| scope.type | string | The type of scope (e.g., `"session"`). |
# 删除文件
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Deleted
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | ID of the deleted file. |
| type | string | Deleted object type. For file deletion, this is always `"file_deleted"`. |
# 下载文件内容
先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Binary content
未声明响应体。
# Claude 托管智能体 API
## 基础地址 [#基础地址]
## 接入 [#接入]
## 运行一次会话 [#运行一次会话]
1. [创建智能体](/docs/api/compatible/anthropic/managed-agents/createAgent)，保存返回的 `agent_…` ID。
2. [创建会话](/docs/api/compatible/anthropic/managed-agents/createSession)，将 `agent` 替换为该 ID，保存 `sesn_…` ID。
3. 先[订阅事件流](/docs/api/compatible/anthropic/managed-agents/streamEvents)，再[发送消息](/docs/api/compatible/anthropic/managed-agents/sendEvents)。将两个请求的会话 ID 替换为同一个真实 ID。
4. 收到 `agent.message` 后等待 `session.status_idle`；也可[查询历史事件](/docs/api/compatible/anthropic/managed-agents/listEvents)。
SDK 基础地址就是上面的基础地址。每个请求均需 API Key、`anthropic-version: 2023-06-01` 和 `anthropic-beta: managed-agents-2026-04-01`。在线试调会自动带上这些协议头，资源 ID 需自行替换。
官方 95 个操作已全部声明：其中 41 个已支持或部分支持（见端点清单徽标）；其余 54 个平台尚未实现，调用如实返回 501（not\_implemented\_error，响应带 x-should-retry: false），不产生任何副作用、不计费。各项能力与凭据库的具体限制见端点说明。
## 端点 [#端点]
### 智能体（6 个端点，6 个可用） [#智能体6-个端点6-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | --------------------------------------------------------------------------------------------------- | ----- | ------ |
| POST | [`/v1/agents`](/docs/api/compatible/anthropic/managed-agents/createAgent) | 创建智能体 | ◐ 部分支持 |
| GET | [`/v1/agents`](/docs/api/compatible/anthropic/managed-agents/listAgents) | 列出智能体 | ● 支持 |
| GET | [`/v1/agents/{agent_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveAgent) | 读取智能体 | ● 支持 |
| POST | [`/v1/agents/{agent_id}`](/docs/api/compatible/anthropic/managed-agents/updateAgent) | 更新智能体 | ◐ 部分支持 |
| GET | [`/v1/agents/{agent_id}/versions`](/docs/api/compatible/anthropic/managed-agents/listAgentVersions) | 列出版本 | ● 支持 |
| POST | [`/v1/agents/{agent_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveAgent) | 归档智能体 | ● 支持 |
### 会话与事件（9 个端点，8 个可用） [#会话与事件9-个端点8-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ------------------------------------------------------------------------------------------------------- | ---- | ------ |
| POST | [`/v1/sessions`](/docs/api/compatible/anthropic/managed-agents/createSession) | 创建会话 | ◐ 部分支持 |
| GET | [`/v1/sessions`](/docs/api/compatible/anthropic/managed-agents/listSessions) | 列出会话 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveSession) | 读取会话 | ● 支持 |
| POST | [`/v1/sessions/{session_id}/events`](/docs/api/compatible/anthropic/managed-agents/sendEvents) | 发送事件 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/events`](/docs/api/compatible/anthropic/managed-agents/listEvents) | 列出事件 | ● 支持 |
| GET | [`/v1/sessions/{session_id}/events/stream`](/docs/api/compatible/anthropic/managed-agents/streamEvents) | 订阅事件 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}`](/docs/api/compatible/anthropic/managed-agents/updateSession) | 更新会话 | ◐ 部分支持 |
| DELETE | [`/v1/sessions/{session_id}`](/docs/api/compatible/anthropic/managed-agents/deleteSession) | 删除会话 | ○ 未支持 |
| POST | [`/v1/sessions/{session_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveSession) | 归档会话 | ● 支持 |
### 定时部署（10 个端点，0 个可用） [#定时部署10-个端点0-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ---------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| GET | [`/v1/deployment_runs`](/docs/api/compatible/anthropic/managed-agents/listDeploymentRuns) | 列出部署运行 | ○ 未支持 |
| GET | [`/v1/deployment_runs/{deployment_run_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveDeploymentRun) | 读取部署运行 | ○ 未支持 |
| GET | [`/v1/deployments`](/docs/api/compatible/anthropic/managed-agents/listDeployments) | 列出部署 | ○ 未支持 |
| POST | [`/v1/deployments`](/docs/api/compatible/anthropic/managed-agents/createDeployment) | 创建部署 | ○ 未支持 |
| GET | [`/v1/deployments/{deployment_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveDeployment) | 读取部署 | ○ 未支持 |
| POST | [`/v1/deployments/{deployment_id}`](/docs/api/compatible/anthropic/managed-agents/updateDeployment) | 更新部署 | ○ 未支持 |
| POST | [`/v1/deployments/{deployment_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveDeployment) | 归档部署 | ○ 未支持 |
| POST | [`/v1/deployments/{deployment_id}/pause`](/docs/api/compatible/anthropic/managed-agents/pauseDeployment) | 暂停部署 | ○ 未支持 |
| POST | [`/v1/deployments/{deployment_id}/run`](/docs/api/compatible/anthropic/managed-agents/runDeployment) | 运行部署 | ○ 未支持 |
| POST | [`/v1/deployments/{deployment_id}/unpause`](/docs/api/compatible/anthropic/managed-agents/unpauseDeployment) | 恢复部署 | ○ 未支持 |
### 环境（6 个端点，5 个可用） [#环境6-个端点5-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | --------------------------------------------------------------------------------------------------------------- | ---- | ------ |
| GET | [`/v1/environments`](/docs/api/compatible/anthropic/managed-agents/listEnvironments) | 列出环境 | ◐ 部分支持 |
| POST | [`/v1/environments`](/docs/api/compatible/anthropic/managed-agents/createEnvironment) | 创建环境 | ◐ 部分支持 |
| DELETE | [`/v1/environments/{environment_id}`](/docs/api/compatible/anthropic/managed-agents/deleteEnvironment) | 删除环境 | ○ 未支持 |
| GET | [`/v1/environments/{environment_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveEnvironment) | 读取环境 | ◐ 部分支持 |
| POST | [`/v1/environments/{environment_id}`](/docs/api/compatible/anthropic/managed-agents/updateEnvironment) | 更新环境 | ◐ 部分支持 |
| POST | [`/v1/environments/{environment_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveEnvironment) | 归档环境 | ◐ 部分支持 |
### 环境任务（8 个端点，0 个可用） [#环境任务8-个端点0-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----- |
| GET | [`/v1/environments/{environment_id}/work`](/docs/api/compatible/anthropic/managed-agents/listEnvironmentWork) | 列出工作项 | ○ 未支持 |
| GET | [`/v1/environments/{environment_id}/work/{work_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveEnvironmentWork) | 读取工作项 | ○ 未支持 |
| POST | [`/v1/environments/{environment_id}/work/{work_id}`](/docs/api/compatible/anthropic/managed-agents/updateEnvironmentWork) | 更新工作项 | ○ 未支持 |
| POST | [`/v1/environments/{environment_id}/work/{work_id}/ack`](/docs/api/compatible/anthropic/managed-agents/ackEnvironmentWork) | 确认工作项 | ○ 未支持 |
| POST | [`/v1/environments/{environment_id}/work/{work_id}/heartbeat`](/docs/api/compatible/anthropic/managed-agents/heartbeatEnvironmentWork) | 工作项心跳 | ○ 未支持 |
| POST | [`/v1/environments/{environment_id}/work/{work_id}/stop`](/docs/api/compatible/anthropic/managed-agents/stopEnvironmentWork) | 停止工作项 | ○ 未支持 |
| GET | [`/v1/environments/{environment_id}/work/poll`](/docs/api/compatible/anthropic/managed-agents/pollEnvironmentWork) | 轮询工作项 | ○ 未支持 |
| GET | [`/v1/environments/{environment_id}/work/stats`](/docs/api/compatible/anthropic/managed-agents/retrieveEnvironmentWorkStats) | 工作项统计 | ○ 未支持 |
### 记忆库（14 个端点，0 个可用） [#记忆库14-个端点0-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| GET | [`/v1/memory_stores`](/docs/api/compatible/anthropic/managed-agents/listMemoryStores) | 列出记忆库 | ○ 未支持 |
| POST | [`/v1/memory_stores`](/docs/api/compatible/anthropic/managed-agents/createMemoryStore) | 创建记忆库 | ○ 未支持 |
| DELETE | [`/v1/memory_stores/{memory_store_id}`](/docs/api/compatible/anthropic/managed-agents/deleteMemoryStore) | 删除记忆库 | ○ 未支持 |
| GET | [`/v1/memory_stores/{memory_store_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveMemoryStore) | 读取记忆库 | ○ 未支持 |
| POST | [`/v1/memory_stores/{memory_store_id}`](/docs/api/compatible/anthropic/managed-agents/updateMemoryStore) | 更新记忆库 | ○ 未支持 |
| POST | [`/v1/memory_stores/{memory_store_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveMemoryStore) | 归档记忆库 | ○ 未支持 |
| GET | [`/v1/memory_stores/{memory_store_id}/memories`](/docs/api/compatible/anthropic/managed-agents/listMemoryStoreMemories) | 列出记忆 | ○ 未支持 |
| POST | [`/v1/memory_stores/{memory_store_id}/memories`](/docs/api/compatible/anthropic/managed-agents/createMemoryStoreMemory) | 创建记忆 | ○ 未支持 |
| DELETE | [`/v1/memory_stores/{memory_store_id}/memories/{memory_id}`](/docs/api/compatible/anthropic/managed-agents/deleteMemoryStoreMemory) | 删除记忆 | ○ 未支持 |
| GET | [`/v1/memory_stores/{memory_store_id}/memories/{memory_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveMemoryStoreMemory) | 读取记忆 | ○ 未支持 |
| POST | [`/v1/memory_stores/{memory_store_id}/memories/{memory_id}`](/docs/api/compatible/anthropic/managed-agents/updateMemoryStoreMemory) | 更新记忆 | ○ 未支持 |
| GET | [`/v1/memory_stores/{memory_store_id}/memory_versions`](/docs/api/compatible/anthropic/managed-agents/listMemoryStoreMemoryVersions) | 列出记忆版本 | ○ 未支持 |
| GET | [`/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveMemoryStoreMemoryVersion) | 读取记忆版本 | ○ 未支持 |
| POST | [`/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact`](/docs/api/compatible/anthropic/managed-agents/redactMemoryStoreMemoryVersion) | 抹除记忆版本 | ○ 未支持 |
### 会话资源（5 个端点，4 个可用） [#会话资源5-个端点4-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------ | ------ |
| GET | [`/v1/sessions/{session_id}/resources`](/docs/api/compatible/anthropic/managed-agents/listSessionResources) | 列出会话资源 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}/resources`](/docs/api/compatible/anthropic/managed-agents/addSessionResource) | 添加会话资源 | ◐ 部分支持 |
| DELETE | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/compatible/anthropic/managed-agents/deleteSessionResource) | 删除会话资源 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveSessionResource) | 读取会话资源 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}/resources/{resource_id}`](/docs/api/compatible/anthropic/managed-agents/updateSessionResource) | 更新会话资源 | ○ 未支持 |
### 会话线程（5 个端点，5 个可用） [#会话线程5-个端点5-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ |
| GET | [`/v1/sessions/{session_id}/threads`](/docs/api/compatible/anthropic/managed-agents/listSessionThreads) | 列出线程 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveSessionThread) | 读取线程 | ◐ 部分支持 |
| POST | [`/v1/sessions/{session_id}/threads/{thread_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveSessionThread) | 归档线程 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}/events`](/docs/api/compatible/anthropic/managed-agents/listSessionThreadEvents) | 列出线程事件 | ◐ 部分支持 |
| GET | [`/v1/sessions/{session_id}/threads/{thread_id}/stream`](/docs/api/compatible/anthropic/managed-agents/streamSessionThreadEvents) | 订阅线程事件 | ◐ 部分支持 |
### 技能（9 个端点，0 个可用） [#技能9-个端点0-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ------------------------------------------------------------------------------------------------------------------------ | -------- | ----- |
| GET | [`/v1/skills`](/docs/api/compatible/anthropic/managed-agents/listSkills) | 列出技能 | ○ 未支持 |
| POST | [`/v1/skills`](/docs/api/compatible/anthropic/managed-agents/createSkill) | 创建技能 | ○ 未支持 |
| DELETE | [`/v1/skills/{skill_id}`](/docs/api/compatible/anthropic/managed-agents/deleteSkill) | 删除技能 | ○ 未支持 |
| GET | [`/v1/skills/{skill_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveSkill) | 读取技能 | ○ 未支持 |
| GET | [`/v1/skills/{skill_id}/versions`](/docs/api/compatible/anthropic/managed-agents/listSkillVersions) | 列出技能版本 | ○ 未支持 |
| POST | [`/v1/skills/{skill_id}/versions`](/docs/api/compatible/anthropic/managed-agents/createSkillVersion) | 创建技能版本 | ○ 未支持 |
| DELETE | [`/v1/skills/{skill_id}/versions/{version}`](/docs/api/compatible/anthropic/managed-agents/deleteSkillVersion) | 删除技能版本 | ○ 未支持 |
| GET | [`/v1/skills/{skill_id}/versions/{version}`](/docs/api/compatible/anthropic/managed-agents/retrieveSkillVersion) | 读取技能版本 | ○ 未支持 |
| GET | [`/v1/skills/{skill_id}/versions/{version}/content`](/docs/api/compatible/anthropic/managed-agents/downloadSkillVersion) | 下载技能版本内容 | ○ 未支持 |
### 隧道（10 个端点，0 个可用） [#隧道10-个端点0-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----- |
| GET | [`/v1/tunnels`](/docs/api/compatible/anthropic/managed-agents/listTunnels) | 列出隧道 | ○ 未支持 |
| POST | [`/v1/tunnels`](/docs/api/compatible/anthropic/managed-agents/createTunnel) | 创建隧道 | ○ 未支持 |
| GET | [`/v1/tunnels/{tunnel_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveTunnel) | 读取隧道 | ○ 未支持 |
| POST | [`/v1/tunnels/{tunnel_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveTunnel) | 归档隧道 | ○ 未支持 |
| GET | [`/v1/tunnels/{tunnel_id}/certificates`](/docs/api/compatible/anthropic/managed-agents/listTunnelCertificates) | 列出隧道证书 | ○ 未支持 |
| POST | [`/v1/tunnels/{tunnel_id}/certificates`](/docs/api/compatible/anthropic/managed-agents/createTunnelCertificate) | 创建隧道证书 | ○ 未支持 |
| GET | [`/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveTunnelCertificate) | 读取隧道证书 | ○ 未支持 |
| POST | [`/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveTunnelCertificate) | 归档隧道证书 | ○ 未支持 |
| POST | [`/v1/tunnels/{tunnel_id}/reveal_token`](/docs/api/compatible/anthropic/managed-agents/revealTunnelToken) | 显示隧道令牌 | ○ 未支持 |
| POST | [`/v1/tunnels/{tunnel_id}/rotate_token`](/docs/api/compatible/anthropic/managed-agents/rotateTunnelToken) | 轮换隧道令牌 | ○ 未支持 |
### 凭据保险库（13 个端点，13 个可用） [#凭据保险库13-个端点13-个可用]
| 方法 | 路径 | 说明 | 支持 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------ |
| GET | [`/v1/vaults`](/docs/api/compatible/anthropic/managed-agents/listVaults) | 列出凭据库 | ● 支持 |
| POST | [`/v1/vaults`](/docs/api/compatible/anthropic/managed-agents/createVault) | 创建凭据库 | ● 支持 |
| DELETE | [`/v1/vaults/{vault_id}`](/docs/api/compatible/anthropic/managed-agents/deleteVault) | 删除凭据库 | ● 支持 |
| GET | [`/v1/vaults/{vault_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveVault) | 读取凭据库 | ● 支持 |
| POST | [`/v1/vaults/{vault_id}`](/docs/api/compatible/anthropic/managed-agents/updateVault) | 更新凭据库 | ● 支持 |
| POST | [`/v1/vaults/{vault_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveVault) | 归档凭据库 | ● 支持 |
| GET | [`/v1/vaults/{vault_id}/credentials`](/docs/api/compatible/anthropic/managed-agents/listVaultCredentials) | 列出凭据 | ◐ 部分支持 |
| POST | [`/v1/vaults/{vault_id}/credentials`](/docs/api/compatible/anthropic/managed-agents/createVaultCredential) | 创建凭据 | ◐ 部分支持 |
| DELETE | [`/v1/vaults/{vault_id}/credentials/{credential_id}`](/docs/api/compatible/anthropic/managed-agents/deleteVaultCredential) | 删除凭据 | ◐ 部分支持 |
| GET | [`/v1/vaults/{vault_id}/credentials/{credential_id}`](/docs/api/compatible/anthropic/managed-agents/retrieveVaultCredential) | 读取凭据 | ◐ 部分支持 |
| POST | [`/v1/vaults/{vault_id}/credentials/{credential_id}`](/docs/api/compatible/anthropic/managed-agents/updateVaultCredential) | 更新凭据 | ◐ 部分支持 |
| POST | [`/v1/vaults/{vault_id}/credentials/{credential_id}/archive`](/docs/api/compatible/anthropic/managed-agents/archiveVaultCredential) | 归档凭据 | ◐ 部分支持 |
| POST | [`/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate`](/docs/api/compatible/anthropic/managed-agents/validateVaultCredentialMcpOAuth) | 校验凭据 MCP OAuth | ◐ 部分支持 |
## 与官方的差异 [#与官方的差异]
* 创建智能体：支持文本提示词、模型、元数据与内置工具。MCP、Skills 及额外模型控制尚不支持，传入会返回 400。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、\{type:"agent",id,version?} 或最多一个 \{type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。兼容 API 只提供 bash、edit、glob、grep、read、write、web\_search、web\_fetch 这 8 个官方工具；configs 不接受其他工具名，经此入口创建的会话不提供后台任务、Monitor 或子智能体。完整原生工具请使用 /agent/v1。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread\_message\_received 返回。
* 读取智能体：将示例中的资源 ID 替换成你创建的资源 ID。
* 更新智能体：version 可用于乐观并发控制，版本冲突返回 409；无变化的更新不增加版本。MCP、Skills 尚不支持。 multiagent 接受 null 或 coordinator 名册，1–20 项：智能体 ID、\{type:"agent",id,version?} 或最多一个 \{type:"self"}。创建/更新时固定版本；成员去重且须存在、未归档、不能自身带 multiagent。兼容 API 只提供 bash、edit、glob、grep、read、write、web\_search、web\_fetch 这 8 个官方工具；configs 不接受其他工具名，经此入口创建的会话不提供后台任务、Monitor 或子智能体。完整原生工具请使用 /agent/v1。每个 coordinator 最多一个 advisor，模型须可用且不同于智能体模型；仅主会话可咨询，每次咨询为独立 advisor 线程，建议以 agent.thread\_message\_received 返回。
* 列出版本：将示例中的资源 ID 替换成你创建的资源 ID。
* 归档智能体：归档后保留查询与历史版本，不能继续更新。请只归档自己的测试智能体。
* 创建会话：先创建智能体，将示例 agent\_123 换成返回的 id。Anthropic 兼容 API 的 environment\_id 必填，可用 node22 或租户自建 cloud 环境；/agent/v1 可省略 environment\_id 得到轻量机器。不支持内联智能体覆盖、预算与凭据库。 支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 列出会话：支持 limit、page 与 agent\_id；agent\_version、时间范围、deployment\_id、memory\_store\_id、include\_archived、order、statuses 尚不支持，传入返回 400。
* 读取会话：将示例中的资源 ID 替换成你创建的资源 ID。
* 发送事件：将 sesn\_123 换成创建会话返回的 id。每条 user.message 只接受一个非空文本块。支持文本 user.message、user.interrupt 和工具确认；其它事件变体尚不支持。返回的是已接纳事件；模型回复从事件历史或订阅读取。会话等待工具授权时发送的 user.message 会排队：返回的事件 processed\_at 为 null，授权处理完成后按发送顺序执行。
* 列出事件：先发送消息再读取历史；处理完成前可能只看到已接纳的输入。支持分页、事件类型和时间过滤。会话等待工具授权时停在 session.status\_idle，stop\_reason 为 requires\_action，event\_ids 列出待确认的 agent.tool\_use；运行失败时先出现 session.error，再出现 session.status\_terminated。agent.thinking 与官方一致，是不带内容的进度信号。
* 订阅事件：保持 SSE 连接以接收事件；请求不会像普通 JSON 接口一样立刻结束。先创建会话并替换 sesn\_123，再从另一请求发送消息；停止按钮只断开订阅，不会停止智能体。SDK 0.124.0 会过滤 session.usage，完整用量请读历史。传 event\_deltas\[]=agent.message 可在最终事件到达前收到逐段文本预览；agent.thinking 与官方一致，只有 event\_start。
* 列出环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 创建环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 读取环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 更新环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 归档环境：支持租户自建 cloud 环境、配置更新与软归档；内置环境只读。列表支持 limit、page 和 include\_archived。limited 网络在沙箱创建时生效；安装失败会终止会话，错误码为 ENVIRONMENT\_PACKAGE\_INSTALL\_FAILED。self\_hosted、scope 和跨会话包缓存尚不支持。
* 更新会话：支持 title 与 metadata（官方补丁语义：字符串值写入、null 删除该键、整包 null 清空，未提及的键保留）。官方的 agent 覆盖（tools/mcp\_servers）、budget 与 vault\_ids 不支持，传入返回 400 并点名字段。归档后的会话更新返回 409。
* 归档会话：归档后的会话拒绝新消息（400 invalid\_request\_error，写明会话已归档），读取与事件历史仍可用；重复归档幂等，archived\_at 保持首次归档时间。
* 列出会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 添加会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 删除会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 读取会话资源：支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/\，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
* 列出线程：按 created\_at 升序返回主线程及全部子线程。线程 id 为 sthr\_ 加所属会话 id 的后缀；子线程的 parent\_thread\_id 指向主线程，session\_id 始终为父会话。agent 是实际运行的定义，内置类型的 name 为类型名，未注册的 id/version 为 null。归档子线程的 status 为 terminated，archived\_at 为归档时间；stats/usage 无线程级追踪时如实为 null。
* 读取线程：返回本会话的主线程或子线程，与列表项逐字段一致。其他会话的线程、未知线程或非 sthr\_ id 一律返回 404，不泄露其存在性。
* 归档线程：主线程沿用会话归档动作；子线程仅归档对应子会话，不归档父会话或其他子线程。子线程归档后 status 为 terminated，带 archived\_at；历史事件仍可读。
* 列出线程事件：读取所选线程自己的事件记录：主线程读主会话，子线程读对应子会话。沿用会话事件接口的查询参数、公开事件类型和 data + next\_page 信封。使用网页工具时，两个接口均返回 search\_result 块；回答 citations 为 /agent/v1 扩展，/anthropic 将引用显示为正文 \[n]。
* 订阅线程事件：订阅所选线程自己的实时事件流。复用会话 SSE 实现；/agent 接口支持同址只读 WebSocket。主会话流同时包含子线程创建、状态和消息事件，子线程审批带 session\_thread\_id 上浮；确认或中断携带该字段时路由到所属子线程。
* 列出凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 创建凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 删除凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 读取凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 更新凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 归档凭据库：支持创建、列出、读取、更新、归档与删除。列表支持 limit、page 和 include\_archived。归档会同时归档库内全部凭据并清除凭据的值；删除会一并删除全部凭据，不可恢复。以 anthropic. 开头的 metadata 键由平台保留，不能写入。同一个库也可以通过原生接口 /vault/v1 管理。
* 列出凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 创建凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 删除凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 读取凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 更新凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 归档凭据：支持 environment\_variable 与 static\_bearer。environment\_variable 的 networking 只支持 limited，传 unrestricted 返回 400；secret\_name 只能使用大写字母、数字和下划线，且不能以数字开头；injection\_location 的默认值与官方一致。static\_bearer 的令牌只在 mcp\_server\_url 所在主机上可用。创建或更新 mcp\_oauth 返回 501（not\_implemented\_error），不产生副作用，官方 SDK 不会重试；需要 OAuth 令牌时请使用 /vault/v1/authorizations 一键授权。每个库最多 20 个有效凭据。以 anthropic. 开头的 metadata 键由平台保留，不能写入。
* 校验凭据 MCP OAuth：只适用于 OAuth 凭据，对其他类型返回 400。结果总是 HTTP 200，status 为 valid、invalid 或 unknown；mcp\_probe 只在未通过时给出失败的一步，refresh 只在尝试了续期时给出。
参数与字段的权威定义以 [Claude Managed Agents 官方文档](https://platform.claude.com/docs/en/managed-agents/overview)为准。
错误按 Claude Managed Agents 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | |
| mcp_servers | array<object> | |
| mcp_servers[].name | string | |
| mcp_servers[].type | string | |
| mcp_servers[].url | string | |
| metadata | object | |
| model | object | Model identifier and configuration. |
| model.id | string | The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| model.effort | object | How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. |
| model.inference_geo | string | Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. |
| model.speed | string | Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. |
| multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| multiagent.agents | array<object> | Agents the coordinator may spawn as session threads, each resolved to a specific version. |
| multiagent.type | string | |
| name | string | |
| skills | array<object> | |
| skills[].skill_id | string | |
| skills[].type | string | |
| skills[].version | string | |
| system | null | string | |
| tools | array<object> | |
| tools[].configs | array<object> | |
| tools[].default_config | object | Resolved default configuration for agent tools. / Resolved default configuration for all tools from an MCP server. |
| tools[].type | string | |
| tools[].mcp_server_name | string | |
| tools[].description | string | |
| tools[].input_schema | object | JSON Schema for custom tool input parameters. |
| tools[].name | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
# 列出智能体
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].description | null | string | |
| data[].mcp_servers | array<object> | |
| data[].metadata | object | |
| data[].model | object | Model identifier and configuration. |
| data[].multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| data[].name | string | |
| data[].skills | array<object> | |
| data[].system | null | string | |
| data[].tools | array<object> | |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
| next_page | string | null | |
# 读取智能体
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | |
| mcp_servers | array<object> | |
| mcp_servers[].name | string | |
| mcp_servers[].type | string | |
| mcp_servers[].url | string | |
| metadata | object | |
| model | object | Model identifier and configuration. |
| model.id | string | The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| model.effort | object | How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. |
| model.inference_geo | string | Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. |
| model.speed | string | Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. |
| multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| multiagent.agents | array<object> | Agents the coordinator may spawn as session threads, each resolved to a specific version. |
| multiagent.type | string | |
| name | string | |
| skills | array<object> | |
| skills[].skill_id | string | |
| skills[].type | string | |
| skills[].version | string | |
| system | null | string | |
| tools | array<object> | |
| tools[].configs | array<object> | |
| tools[].default_config | object | Resolved default configuration for agent tools. / Resolved default configuration for all tools from an MCP server. |
| tools[].type | string | |
| tools[].mcp_server_name | string | |
| tools[].description | string | |
| tools[].input_schema | object | JSON Schema for custom tool input parameters. |
| tools[].name | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
#
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | |
| mcp_servers | array<object> | |
| mcp_servers[].name | string | |
| mcp_servers[].type | string | |
| mcp_servers[].url | string | |
| metadata | object | |
| model | object | Model identifier and configuration. |
| model.id | string | The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| model.effort | object | How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. |
| model.inference_geo | string | Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. |
| model.speed | string | Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. |
| multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| multiagent.agents | array<object> | Agents the coordinator may spawn as session threads, each resolved to a specific version. |
| multiagent.type | string | |
| name | string | |
| skills | array<object> | |
| skills[].skill_id | string | |
| skills[].type | string | |
| skills[].version | string | |
| system | null | string | |
| tools | array<object> | |
| tools[].configs | array<object> | |
| tools[].default_config | object | Resolved default configuration for agent tools. / Resolved default configuration for all tools from an MCP server. |
| tools[].type | string | |
| tools[].mcp_server_name | string | |
| tools[].description | string | |
| tools[].input_schema | object | JSON Schema for custom tool input parameters. |
| tools[].name | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
# 列出版本
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].description | null | string | |
| data[].mcp_servers | array<object> | |
| data[].metadata | object | |
| data[].model | object | Model identifier and configuration. |
| data[].multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| data[].name | string | |
| data[].skills | array<object> | |
| data[].system | null | string | |
| data[].tools | array<object> | |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
| next_page | string | null | |
# 归档智能体
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | |
| mcp_servers | array<object> | |
| mcp_servers[].name | string | |
| mcp_servers[].type | string | |
| mcp_servers[].url | string | |
| metadata | object | |
| model | object | Model identifier and configuration. |
| model.id | string | The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. |
| model.effort | object | How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. |
| model.inference_geo | string | Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. |
| model.speed | string | Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. |
| multiagent | null | object | Resolved coordinator topology with a concrete agent roster. |
| multiagent.agents | array<object> | Agents the coordinator may spawn as session threads, each resolved to a specific version. |
| multiagent.type | string | |
| name | string | |
| skills | array<object> | |
| skills[].skill_id | string | |
| skills[].type | string | |
| skills[].version | string | |
| system | null | string | |
| tools | array<object> | |
| tools[].configs | array<object> | |
| tools[].default_config | object | Resolved default configuration for agent tools. / Resolved default configuration for all tools from an MCP server. |
| tools[].type | string | |
| tools[].mcp_server_name | string | |
| tools[].description | string | |
| tools[].input_schema | object | JSON Schema for custom tool input parameters. |
| tools[].name | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| version | number | The agent's current version. Starts at 1 and increments when the agent is modified. |
#
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.model | object | Model identifier and configuration. |
| agent.multiagent | null | object | Resolved coordinator topology with full agent definitions for each roster member. |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | |
| metadata | object | |
| outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| outcome_evaluations[].completed_at | null | string | A timestamp in RFC 3339 format |
| outcome_evaluations[].description | string | What the agent should produce. |
| outcome_evaluations[].explanation | null | string | Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable. |
| outcome_evaluations[].iteration | number | 0-indexed revision cycle the outcome is currently on. |
| outcome_evaluations[].outcome_id | string | Server-generated outc\_ ID for this outcome. |
| outcome_evaluations[].result | string | Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. |
| outcome_evaluations[].type | string | |
| resources | array<object> | |
| resources[].id | string | |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| resources[].type | string | |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | |
| resources[].checkout | null | object | |
| resources[].file_id | string | |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| resources[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| stats | object | Timing statistics for a session. |
| stats.active_seconds | number | Cumulative time in seconds the session spent in `running` status. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. |
| status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| title | null | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | object | Cumulative token usage for a session across all turns. |
| usage.active_seconds | number | Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
| vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | |
| data[].agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].environment_id | string | |
| data[].metadata | object | |
| data[].outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| data[].resources | array<object> | |
| data[].stats | object | Timing statistics for a session. |
| data[].status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| data[].title | null | string | |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].usage | object | Cumulative token usage for a session across all turns. |
| data[].vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| data[].deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |
| next_page | string | null | |
# 读取会话
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.model | object | Model identifier and configuration. |
| agent.multiagent | null | object | Resolved coordinator topology with full agent definitions for each roster member. |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | |
| metadata | object | |
| outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| outcome_evaluations[].completed_at | null | string | A timestamp in RFC 3339 format |
| outcome_evaluations[].description | string | What the agent should produce. |
| outcome_evaluations[].explanation | null | string | Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable. |
| outcome_evaluations[].iteration | number | 0-indexed revision cycle the outcome is currently on. |
| outcome_evaluations[].outcome_id | string | Server-generated outc\_ ID for this outcome. |
| outcome_evaluations[].result | string | Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. |
| outcome_evaluations[].type | string | |
| resources | array<object> | |
| resources[].id | string | |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| resources[].type | string | |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | |
| resources[].checkout | null | object | |
| resources[].file_id | string | |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| resources[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| stats | object | Timing statistics for a session. |
| stats.active_seconds | number | Cumulative time in seconds the session spent in `running` status. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. |
| status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| title | null | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | object | Cumulative token usage for a session across all turns. |
| usage.active_seconds | number | Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
| vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | Sent events |
| data[].id | string | Unique identifier for this event. |
| data[].content | array<object> | Array of content blocks comprising the user message. / The result content returned by the tool. / The result content returned by the tool. / System content blocks. Text-only. |
| data[].type | string | |
| data[].processed_at | null | string | string | null | string | null | string | A timestamp in RFC 3339 format |
| data[].session_thread_id | null | string | If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. / Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. |
| data[].result | string | UserToolConfirmationResult enum |
| data[].tool_use_id | string | The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. / The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].deny_message | null | string | Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. |
| data[].custom_tool_use_id | string | The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].is_error | null | boolean | Whether the tool execution resulted in an error. |
| data[].description | string | What the agent should produce. Copied from the input event. |
| data[].max_iterations | null | number | Evaluate-then-revise cycles before giving up. Default 3, max 20. |
| data[].outcome_id | string | Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. |
| data[].rubric | object | Rubric for grading the quality of an outcome. |
# 列出事件
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this event. |
| data[].content | array<object> | Array of content blocks comprising the user message. / The result content returned by the tool. / Array of text blocks comprising the agent response. / The result content returned by the tool. / The result content returned by the tool. / Message content blocks. / Message content blocks. / The result content returned by the tool. / System content blocks. Text-only. |
| data[].type | string | |
| data[].processed_at | null | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | null | string | string | string | null | string | string | A timestamp in RFC 3339 format |
| data[].session_thread_id | null | string | string | string | string | string | null | string | string | If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. / Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. / When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. / When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. / Public `sthr_` ID of the newly created thread. / Public sthr\_ ID of the thread that started running. / Public sthr\_ ID of the thread that went idle. / Public sthr\_ ID of the thread that terminated. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / Public sthr\_ ID of the thread that is retrying. |
| data[].result | string | UserToolConfirmationResult enum / Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. |
| data[].tool_use_id | string | The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. / The id of the `agent.tool_use` event this result corresponds to. / The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].deny_message | null | string | Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. |
| data[].custom_tool_use_id | string | The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].is_error | null | boolean | Whether the tool execution resulted in an error. / Whether the model request resulted in an error. / Whether the tool execution resulted in an error. |
| data[].input | object | Input parameters for the tool call. |
| data[].name | string | Name of the custom tool being called. / Name of the MCP tool being used. / Name of the agent tool being used. |
| data[].mcp_server_name | string | Name of the MCP server providing the tool. |
| data[].evaluated_permission | string | AgentEvaluatedPermission enum |
| data[].evaluation | object | Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants. |
| data[].mcp_tool_use_id | string | The id of the `agent.mcp_tool_use` event this result corresponds to. |
| data[].from_session_thread_id | string | Public `sthr_` ID of the thread that sent the message. |
| data[].from_agent_name | null | string | Name of the callable agent this message came from. Absent when received from the primary agent. |
| data[].to_session_thread_id | string | Public `sthr_` ID of the thread the message was sent to. |
| data[].to_agent_name | null | string | Name of the callable agent this message was sent to. Absent when sent to the primary agent. |
| data[].error | object | |
| data[].stop_reason | object | |
| data[].agent_name | string | Name of the callable agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. |
| data[].iteration | number | 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. / 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. / 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. |
| data[].outcome_id | string | The `outc_` ID of the outcome being evaluated. / Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. |
| data[].explanation | string | Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. |
| data[].outcome_evaluation_start_id | string | The id of the corresponding `span.outcome_evaluation_start` event. |
| data[].usage | object | Token usage for a single model request. / Point-in-time snapshot of a session's cumulative usage. |
| data[].model_request_start_id | string | The id of the corresponding `span.model_request_start` event. |
| data[].model_usage | object | Token usage for a single model request. |
| data[].description | string | What the agent should produce. Copied from the input event. |
| data[].max_iterations | null | number | Evaluate-then-revise cycles before giving up. Default 3, max 20. |
| data[].rubric | object | Rubric for grading the quality of an outcome. |
| data[].agent | null | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| data[].budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| data[].metadata | object | The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. |
| data[].title | null | string | The session's new title. Present only when the update changed it. |
| next_page | string | null | |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Server-sent events
**text/event-stream — chunk / 事件对象**
未声明字段结构。
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this run (`drun_...`). |
| data[].agent | object | A resolved agent reference with a concrete version. |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].deployment_id | string | ID of the deployment that produced this run. |
| data[].error | null | object | Why the run failed to create a session. The type identifies the failure; message is human-readable detail. |
| data[].session_id | null | string | Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. |
| data[].trigger_context | object | Describes what triggered a deployment run, with trigger-specific metadata. |
| data[].type | string | |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this run (`drun_...`). |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| created_at | string | A timestamp in RFC 3339 format |
| deployment_id | string | ID of the deployment that produced this run. |
| error | null | object | Why the run failed to create a session. The type identifies the failure; message is human-readable detail. |
| error.message | string | Human-readable error description. |
| error.type | string | |
| session_id | null | string | Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. |
| trigger_context | object | Describes what triggered a deployment run, with trigger-specific metadata. |
| trigger_context.scheduled_at | string | A timestamp in RFC 3339 format |
| trigger_context.type | string | |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this deployment. |
| data[].agent | object | A resolved agent reference with a concrete version. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].description | null | string | Description of what the deployment does. |
| data[].environment_id | string | ID of the `environment` where sessions run. |
| data[].initial_events | array<object> | Events sent to each session immediately after creation. |
| data[].metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| data[].name | string | Human-readable name. |
| data[].paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| data[].resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| data[].schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| data[].status | string | Lifecycle status of a deployment. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| data[].budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this run (`drun_...`). |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| created_at | string | A timestamp in RFC 3339 format |
| deployment_id | string | ID of the deployment that produced this run. |
| error | null | object | Why the run failed to create a session. The type identifies the failure; message is human-readable detail. |
| error.message | string | Human-readable error description. |
| error.type | string | |
| session_id | null | string | Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. |
| trigger_context | object | Describes what triggered a deployment run, with trigger-specific metadata. |
| trigger_context.scheduled_at | string | A timestamp in RFC 3339 format |
| trigger_context.type | string | |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this deployment. |
| agent | object | A resolved agent reference with a concrete version. |
| agent.id | string | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| description | null | string | Description of what the deployment does. |
| environment_id | string | ID of the `environment` where sessions run. |
| initial_events | array<object> | Events sent to each session immediately after creation. |
| initial_events[].content | array<object> | Array of content blocks for the user message. / System content blocks to append. Text-only. |
| initial_events[].type | string | |
| initial_events[].description | string | What the agent should produce. This is the task specification. |
| initial_events[].rubric | object | Rubric for grading the quality of an outcome. |
| initial_events[].max_iterations | null | number | Eval→revision cycles before giving up. Default 3, max 20. |
| metadata | object | Arbitrary key-value metadata. Maximum 16 pairs. |
| name | string | Human-readable name. |
| paused_reason | null | object | Why a deployment is paused. Non-null exactly when `status` is `paused`. |
| paused_reason.type | string | |
| paused_reason.error | object | The error that triggered an auto-pause. Matches the failed run's `error.type`. |
| resources | array<object> | Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. |
| resources[].type | string | |
| resources[].url | string | Github URL of the repository |
| resources[].checkout | null | object | Branch or commit to check out. Defaults to the repository's default branch. |
| resources[].mount_path | null | string | Mount path in the container. Defaults to `/workspace/<repo-name>`. / Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. |
| resources[].file_id | string | ID of a previously uploaded file. |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| schedule | null | object | 5-field POSIX cron schedule with computed runtime timestamps. |
| schedule.expression | string | 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 \* \* 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily). |
| schedule.timezone | string | IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). |
| schedule.type | string | |
| schedule.last_run_at | null | string | A timestamp in RFC 3339 format |
| schedule.upcoming_runs_at | array<string> | Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time. |
| status | string | Lifecycle status of a deployment. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_ids | array<string> | Vault IDs supplying stored credentials for sessions created from this deployment. |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Environment identifier (e.g., 'env\_...') |
| data[].archived_at | null | string | RFC 3339 timestamp when environment was archived, or null if not archived |
| data[].config | object | Environment configuration (either Anthropic Cloud or self-hosted) |
| data[].created_at | string | RFC 3339 timestamp when environment was created |
| data[].description | null | string | User-provided description for the environment; null when unset |
| data[].metadata | object | User-provided metadata key-value pairs |
| data[].name | string | Human-readable name for the environment |
| data[].type | string | The type of object (always 'environment') |
| data[].updated_at | string | RFC 3339 timestamp when environment was last updated |
| data[].scope | string | The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Environment identifier (e.g., 'env\_...') |
| archived_at | null | string | RFC 3339 timestamp when environment was archived, or null if not archived |
| config | object | Environment configuration (either Anthropic Cloud or self-hosted) |
| config.networking | object | Network configuration policy. |
| config.packages | object | Package manager configuration. |
| config.type | string | Environment type |
| created_at | string | RFC 3339 timestamp when environment was created |
| description | null | string | User-provided description for the environment; null when unset |
| metadata | object | User-provided metadata key-value pairs |
| name | string | Human-readable name for the environment |
| type | string | The type of object (always 'environment') |
| updated_at | string | RFC 3339 timestamp when environment was last updated |
| scope | string | The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Environment identifier |
| type | string | The type of response |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Environment identifier (e.g., 'env\_...') |
| archived_at | null | string | RFC 3339 timestamp when environment was archived, or null if not archived |
| config | object | Environment configuration (either Anthropic Cloud or self-hosted) |
| config.networking | object | Network configuration policy. |
| config.packages | object | Package manager configuration. |
| config.type | string | Environment type |
| created_at | string | RFC 3339 timestamp when environment was created |
| description | null | string | User-provided description for the environment; null when unset |
| metadata | object | User-provided metadata key-value pairs |
| name | string | Human-readable name for the environment |
| type | string | The type of object (always 'environment') |
| updated_at | string | RFC 3339 timestamp when environment was last updated |
| scope | string | The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Environment identifier (e.g., 'env\_...') |
| archived_at | null | string | RFC 3339 timestamp when environment was archived, or null if not archived |
| config | object | Environment configuration (either Anthropic Cloud or self-hosted) |
| config.networking | object | Network configuration policy. |
| config.packages | object | Package manager configuration. |
| config.type | string | Environment type |
| created_at | string | RFC 3339 timestamp when environment was created |
| description | null | string | User-provided description for the environment; null when unset |
| metadata | object | User-provided metadata key-value pairs |
| name | string | Human-readable name for the environment |
| type | string | The type of object (always 'environment') |
| updated_at | string | RFC 3339 timestamp when environment was last updated |
| scope | string | The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Environment identifier (e.g., 'env\_...') |
| archived_at | null | string | RFC 3339 timestamp when environment was archived, or null if not archived |
| config | object | Environment configuration (either Anthropic Cloud or self-hosted) |
| config.networking | object | Network configuration policy. |
| config.packages | object | Package manager configuration. |
| config.type | string | Environment type |
| created_at | string | RFC 3339 timestamp when environment was created |
| description | null | string | User-provided description for the environment; null when unset |
| metadata | object | User-provided metadata key-value pairs |
| name | string | Human-readable name for the environment |
| type | string | The type of object (always 'environment') |
| updated_at | string | RFC 3339 timestamp when environment was last updated |
| scope | string | The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Work identifier (e.g., 'work\_...') |
| data[].acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| data[].created_at | string | RFC 3339 timestamp when work was created |
| data[].data | object | The actual work to be performed (session or health check) |
| data[].environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| data[].latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| data[].metadata | object | User-provided metadata key-value pairs associated with this work item |
| data[].secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| data[].started_at | null | string | RFC 3339 timestamp when work execution started |
| data[].state | string | Current state of the work item |
| data[].stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| data[].stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| data[].type | string | The type of object (always 'work') |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Work identifier (e.g., 'work\_...') |
| acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| created_at | string | RFC 3339 timestamp when work was created |
| data | object | The actual work to be performed (session or health check) |
| data.id | string | Session identifier (e.g., 'session\_...') / Health check identifier |
| data.type | string | Type of work data |
| environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| metadata | object | User-provided metadata key-value pairs associated with this work item |
| secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| started_at | null | string | RFC 3339 timestamp when work execution started |
| state | string | Current state of the work item |
| stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| type | string | The type of object (always 'work') |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Work identifier (e.g., 'work\_...') |
| acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| created_at | string | RFC 3339 timestamp when work was created |
| data | object | The actual work to be performed (session or health check) |
| data.id | string | Session identifier (e.g., 'session\_...') / Health check identifier |
| data.type | string | Type of work data |
| environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| metadata | object | User-provided metadata key-value pairs associated with this work item |
| secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| started_at | null | string | RFC 3339 timestamp when work execution started |
| state | string | Current state of the work item |
| stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| type | string | The type of object (always 'work') |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Work identifier (e.g., 'work\_...') |
| acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| created_at | string | RFC 3339 timestamp when work was created |
| data | object | The actual work to be performed (session or health check) |
| data.id | string | Session identifier (e.g., 'session\_...') / Health check identifier |
| data.type | string | Type of work data |
| environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| metadata | object | User-provided metadata key-value pairs associated with this work item |
| secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| started_at | null | string | RFC 3339 timestamp when work execution started |
| state | string | Current state of the work item |
| stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| type | string | The type of object (always 'work') |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| last_heartbeat | string | RFC 3339 timestamp of the actual heartbeat from DB |
| lease_extended | boolean | Whether the heartbeat succeeded in extending the lease |
| state | string | Current state of the work item (active/stopping/stopped) |
| ttl_seconds | number | Effective TTL applied to the lease |
| type | string | The type of response |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Work identifier (e.g., 'work\_...') |
| acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| created_at | string | RFC 3339 timestamp when work was created |
| data | object | The actual work to be performed (session or health check) |
| data.id | string | Session identifier (e.g., 'session\_...') / Health check identifier |
| data.type | string | Type of work data |
| environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| metadata | object | User-provided metadata key-value pairs associated with this work item |
| secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| started_at | null | string | RFC 3339 timestamp when work execution started |
| state | string | Current state of the work item |
| stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| type | string | The type of object (always 'work') |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Work identifier (e.g., 'work\_...') |
| acknowledged_at | null | string | RFC 3339 timestamp when work was acknowledged by Environment Manager |
| created_at | string | RFC 3339 timestamp when work was created |
| data | object | The actual work to be performed (session or health check) |
| data.id | string | Session identifier (e.g., 'session\_...') / Health check identifier |
| data.type | string | Type of work data |
| environment_id | string | Environment identifier this work belongs to (e.g., `env_...`) |
| latest_heartbeat_at | null | string | RFC 3339 timestamp of the most recent heartbeat |
| metadata | object | User-provided metadata key-value pairs associated with this work item |
| secret | null | string | Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. |
| started_at | null | string | RFC 3339 timestamp when work execution started |
| state | string | Current state of the work item |
| stop_requested_at | null | string | RFC 3339 timestamp when stop was requested |
| stopped_at | null | string | RFC 3339 timestamp when work execution stopped |
| type | string | The type of object (always 'work') |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| depth | number | Number of work items waiting to be picked up (lag from consumer group) |
| oldest_queued_at | null | string | RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty |
| pending | number | Number of work items being processed (polled but not acknowledged) |
| type | string | The type of object |
| workers_polling | null | number | Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].name | string | Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].description | string | Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. |
| data[].metadata | object | Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. |
| created_at | string | A timestamp in RFC 3339 format |
| name | string | Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| archived_at | null | string | A timestamp in RFC 3339 format |
| description | string | Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. |
| metadata | object | Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. |
| created_at | string | A timestamp in RFC 3339 format |
| name | string | Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| archived_at | null | string | A timestamp in RFC 3339 format |
| description | string | Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. |
| metadata | object | Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. |
| created_at | string | A timestamp in RFC 3339 format |
| name | string | Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| archived_at | null | string | A timestamp in RFC 3339 format |
| description | string | Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. |
| metadata | object | Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. |
| created_at | string | A timestamp in RFC 3339 format |
| name | string | Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| archived_at | null | string | A timestamp in RFC 3339 format |
| description | string | Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. |
| metadata | object | Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. |
| data[].content_sha256 | string | Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. |
| data[].content_size_bytes | number | Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].memory_store_id | string | ID of the memory store this memory belongs to (a `memstore_...` value). |
| data[].memory_version_id | string | ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/en/api/beta/memory_stores/memory_versions/list). |
| data[].path | string | Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. / The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].content | null | string | The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. |
| content_sha256 | string | Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. |
| content_size_bytes | number | Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. |
| created_at | string | A timestamp in RFC 3339 format |
| memory_store_id | string | ID of the memory store this memory belongs to (a `memstore_...` value). |
| memory_version_id | string | ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/en/api/beta/memory_stores/memory_versions/list). |
| path | string | Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| content | null | string | The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | ID of the deleted memory (a `mem_...` value). |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. |
| content_sha256 | string | Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. |
| content_size_bytes | number | Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. |
| created_at | string | A timestamp in RFC 3339 format |
| memory_store_id | string | ID of the memory store this memory belongs to (a `memstore_...` value). |
| memory_version_id | string | ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/en/api/beta/memory_stores/memory_versions/list). |
| path | string | Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| content | null | string | The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. |
| content_sha256 | string | Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. |
| content_size_bytes | number | Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. |
| created_at | string | A timestamp in RFC 3339 format |
| memory_store_id | string | ID of the memory store this memory belongs to (a `memstore_...` value). |
| memory_version_id | string | ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the history via [List memory versions](/en/api/beta/memory_stores/memory_versions/list). |
| path | string | Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| content | null | string | The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this version (a `memver_...` value). |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].memory_id | string | ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/en/api/beta/memory_stores/memory_versions/list) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. |
| data[].memory_store_id | string | ID of the memory store this version belongs to (a `memstore_...` value). |
| data[].operation | string | The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. |
| data[].type | string | |
| data[].content | null | string | The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. |
| data[].content_sha256 | null | string | Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| data[].content_size_bytes | null | number | Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| data[].created_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| data[].path | null | string | The memory's path at the time of this write. `null` if and only if `redacted_at` is set. |
| data[].redacted_at | null | string | A timestamp in RFC 3339 format |
| data[].redacted_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this version (a `memver_...` value). |
| created_at | string | A timestamp in RFC 3339 format |
| memory_id | string | ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/en/api/beta/memory_stores/memory_versions/list) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. |
| memory_store_id | string | ID of the memory store this version belongs to (a `memstore_...` value). |
| operation | string | The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. |
| type | string | |
| content | null | string | The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. |
| content_sha256 | null | string | Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| content_size_bytes | null | number | Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| created_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| created_by.session_id | string | ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/en/api/beta/sessions/retrieve) for further provenance. |
| created_by.type | string | |
| created_by.api_key_id | string | ID of the API key that performed the write. This identifies the key, not the secret. |
| created_by.user_id | string | ID of the user who performed the write (a `user_...` value). |
| created_by.service_account_id | string | ID of the service account that performed the write (a `svac_...` value). |
| path | null | string | The memory's path at the time of this write. `null` if and only if `redacted_at` is set. |
| redacted_at | null | string | A timestamp in RFC 3339 format |
| redacted_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| redacted_by.session_id | string | ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/en/api/beta/sessions/retrieve) for further provenance. |
| redacted_by.type | string | |
| redacted_by.api_key_id | string | ID of the API key that performed the write. This identifies the key, not the secret. |
| redacted_by.user_id | string | ID of the user who performed the write (a `user_...` value). |
| redacted_by.service_account_id | string | ID of the service account that performed the write (a `svac_...` value). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this version (a `memver_...` value). |
| created_at | string | A timestamp in RFC 3339 format |
| memory_id | string | ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/en/api/beta/memory_stores/memory_versions/list) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. |
| memory_store_id | string | ID of the memory store this version belongs to (a `memstore_...` value). |
| operation | string | The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. |
| type | string | |
| content | null | string | The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. |
| content_sha256 | null | string | Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| content_size_bytes | null | number | Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. |
| created_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| created_by.session_id | string | ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/en/api/beta/sessions/retrieve) for further provenance. |
| created_by.type | string | |
| created_by.api_key_id | string | ID of the API key that performed the write. This identifies the key, not the secret. |
| created_by.user_id | string | ID of the user who performed the write (a `user_...` value). |
| created_by.service_account_id | string | ID of the service account that performed the write (a `svac_...` value). |
| path | null | string | The memory's path at the time of this write. `null` if and only if `redacted_at` is set. |
| redacted_at | null | string | A timestamp in RFC 3339 format |
| redacted_by | object | Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/en/api/beta/sessions/retrieve). |
| redacted_by.session_id | string | ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/en/api/beta/sessions/retrieve) for further provenance. |
| redacted_by.type | string | |
| redacted_by.api_key_id | string | ID of the API key that performed the write. This identifies the key, not the secret. |
| redacted_by.user_id | string | ID of the user who performed the write (a `user_...` value). |
| redacted_by.service_account_id | string | ID of the service account that performed the write (a `svac_...` value). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| type | string | |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.model | object | Model identifier and configuration. |
| agent.multiagent | null | object | Resolved coordinator topology with full agent definitions for each roster member. |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | |
| metadata | object | |
| outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| outcome_evaluations[].completed_at | null | string | A timestamp in RFC 3339 format |
| outcome_evaluations[].description | string | What the agent should produce. |
| outcome_evaluations[].explanation | null | string | Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable. |
| outcome_evaluations[].iteration | number | 0-indexed revision cycle the outcome is currently on. |
| outcome_evaluations[].outcome_id | string | Server-generated outc\_ ID for this outcome. |
| outcome_evaluations[].result | string | Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. |
| outcome_evaluations[].type | string | |
| resources | array<object> | |
| resources[].id | string | |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| resources[].type | string | |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | |
| resources[].checkout | null | object | |
| resources[].file_id | string | |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| resources[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| stats | object | Timing statistics for a session. |
| stats.active_seconds | number | Cumulative time in seconds the session spent in `running` status. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. |
| status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| title | null | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | object | Cumulative token usage for a session across all turns. |
| usage.active_seconds | number | Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
| vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |
# 归档会话
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.model | object | Model identifier and configuration. |
| agent.multiagent | null | object | Resolved coordinator topology with full agent definitions for each roster member. |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | |
| metadata | object | |
| outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| outcome_evaluations[].completed_at | null | string | A timestamp in RFC 3339 format |
| outcome_evaluations[].description | string | What the agent should produce. |
| outcome_evaluations[].explanation | null | string | Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable. |
| outcome_evaluations[].iteration | number | 0-indexed revision cycle the outcome is currently on. |
| outcome_evaluations[].outcome_id | string | Server-generated outc\_ ID for this outcome. |
| outcome_evaluations[].result | string | Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. |
| outcome_evaluations[].type | string | |
| resources | array<object> | |
| resources[].id | string | |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| resources[].type | string | |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | |
| resources[].checkout | null | object | |
| resources[].file_id | string | |
| resources[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| resources[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| stats | object | Timing statistics for a session. |
| stats.active_seconds | number | Cumulative time in seconds the session spent in `running` status. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. |
| status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| title | null | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | object | Cumulative token usage for a session across all turns. |
| usage.active_seconds | number | Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
| vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].url | string | |
| data[].checkout | null | object | |
| data[].file_id | string | |
| data[].memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| data[].access | null | string | Access mode for an attached memory store. |
| data[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| data[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| data[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| created_at | string | A timestamp in RFC 3339 format |
| file_id | string | |
| mount_path | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| created_at | string | A timestamp in RFC 3339 format |
| mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| url | string | |
| checkout | null | object | |
| checkout.name | string | Branch name to check out. |
| checkout.type | string | |
| checkout.sha | string | Full commit SHA to check out. |
| file_id | string | |
| memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| access | null | string | Access mode for an attached memory store. |
| description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| created_at | string | A timestamp in RFC 3339 format |
| mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| url | string | |
| checkout | null | object | |
| checkout.name | string | Branch name to check out. |
| checkout.type | string | |
| checkout.sha | string | Full commit SHA to check out. |
| file_id | string | |
| memory_store_id | string | The memory store ID (memstore\_...). Must belong to the caller's organization and workspace. |
| access | null | string | Access mode for an attached memory store. |
| description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this thread. |
| data[].agent | object | The resolved agent a `session_thread` runs. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].parent_thread_id | null | string | Parent thread that spawned this thread. Null for the primary thread. |
| data[].session_id | string | The session this thread belongs to. |
| data[].stats | null | object | Timing statistics for a session thread. |
| data[].status | string | SessionThreadStatus enum |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].usage | null | object | Cumulative token usage for a session thread across all turns. |
| next_page | string | null | |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this thread. |
| agent | object | The resolved agent a `session_thread` runs. |
| agent.model | string | object | The advisor model id. / Model identifier and configuration. |
| agent.type | string | |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| parent_thread_id | null | string | Parent thread that spawned this thread. Null for the primary thread. |
| session_id | string | The session this thread belongs to. |
| stats | null | object | Timing statistics for a session thread. |
| stats.active_seconds | number | Cumulative time in seconds the thread spent actively running. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. |
| stats.startup_seconds | number | Time in seconds for the thread to begin running. Zero for child threads, which start immediately. |
| status | string | SessionThreadStatus enum |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | null | object | Cumulative token usage for a session thread across all turns. |
| usage.active_seconds | number | Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this thread. |
| agent | object | The resolved agent a `session_thread` runs. |
| agent.model | string | object | The advisor model id. / Model identifier and configuration. |
| agent.type | string | |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| parent_thread_id | null | string | Parent thread that spawned this thread. Null for the primary thread. |
| session_id | string | The session this thread belongs to. |
| stats | null | object | Timing statistics for a session thread. |
| stats.active_seconds | number | Cumulative time in seconds the thread spent actively running. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. |
| stats.startup_seconds | number | Time in seconds for the thread to begin running. Zero for child threads, which start immediately. |
| status | string | SessionThreadStatus enum |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | null | object | Cumulative token usage for a session thread across all turns. |
| usage.active_seconds | number | Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this event. |
| data[].content | array<object> | Array of content blocks comprising the user message. / The result content returned by the tool. / Array of text blocks comprising the agent response. / The result content returned by the tool. / The result content returned by the tool. / Message content blocks. / Message content blocks. / The result content returned by the tool. / System content blocks. Text-only. |
| data[].type | string | |
| data[].processed_at | null | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | string | null | string | string | string | null | string | string | A timestamp in RFC 3339 format |
| data[].session_thread_id | null | string | string | string | string | string | null | string | string | If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. / Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. / When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. / When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. / Public `sthr_` ID of the newly created thread. / Public sthr\_ ID of the thread that started running. / Public sthr\_ ID of the thread that went idle. / Public sthr\_ ID of the thread that terminated. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / Public sthr\_ ID of the thread that is retrying. |
| data[].result | string | UserToolConfirmationResult enum / Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. |
| data[].tool_use_id | string | The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. / The id of the `agent.tool_use` event this result corresponds to. / The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].deny_message | null | string | Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. |
| data[].custom_tool_use_id | string | The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. |
| data[].is_error | null | boolean | Whether the tool execution resulted in an error. / Whether the model request resulted in an error. / Whether the tool execution resulted in an error. |
| data[].input | object | Input parameters for the tool call. |
| data[].name | string | Name of the custom tool being called. / Name of the MCP tool being used. / Name of the agent tool being used. |
| data[].mcp_server_name | string | Name of the MCP server providing the tool. |
| data[].evaluated_permission | string | AgentEvaluatedPermission enum |
| data[].evaluation | object | Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants. |
| data[].mcp_tool_use_id | string | The id of the `agent.mcp_tool_use` event this result corresponds to. |
| data[].from_session_thread_id | string | Public `sthr_` ID of the thread that sent the message. |
| data[].from_agent_name | null | string | Name of the callable agent this message came from. Absent when received from the primary agent. |
| data[].to_session_thread_id | string | Public `sthr_` ID of the thread the message was sent to. |
| data[].to_agent_name | null | string | Name of the callable agent this message was sent to. Absent when sent to the primary agent. |
| data[].error | object | |
| data[].stop_reason | object | |
| data[].agent_name | string | Name of the callable agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. / Name of the agent the thread runs. |
| data[].iteration | number | 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. / 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. / 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. |
| data[].outcome_id | string | The `outc_` ID of the outcome being evaluated. / Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. |
| data[].explanation | string | Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. |
| data[].outcome_evaluation_start_id | string | The id of the corresponding `span.outcome_evaluation_start` event. |
| data[].usage | object | Token usage for a single model request. / Point-in-time snapshot of a session's cumulative usage. |
| data[].model_request_start_id | string | The id of the corresponding `span.model_request_start` event. |
| data[].model_usage | object | Token usage for a single model request. |
| data[].description | string | What the agent should produce. Copied from the input event. |
| data[].max_iterations | null | number | Evaluate-then-revise cycles before giving up. Default 3, max 20. |
| data[].rubric | object | Rubric for grading the quality of an outcome. |
| data[].agent | null | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| data[].budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| data[].metadata | object | The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. |
| data[].title | null | string | The session's new title. Present only when the update changed it. |
| next_page | string | null | |
#
先调用「创建会话」，用返回的会话 ID 替换示例 ID。
## 响应 [#响应]
### HTTP 200 [#http-200]
Server-sent events
**text/event-stream — chunk / 事件对象**
未声明字段结构。
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| data[].created_at | string | ISO 8601 timestamp of when the skill was created. |
| data[].display_name | string | Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. |
| data[].latest_version_id | string | ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. |
| data[].source | object | Where the Skill comes from. Possible values: - `"custom"`: authored by the platform user; private to their workspace - `"anthropic"`: published by Anthropic; shared and read-only - `"anthropic_example"`: Anthropic-published sample Skill - `"plugin"`: resolved from an installed plugin |
| data[].type | string | Object type. For Skills, this is always `"skill"`. |
| data[].updated_at | string | ISO 8601 timestamp of when the skill was last updated. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**multipart/form-data**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| created_at | string | ISO 8601 timestamp of when the skill was created. |
| display_name | string | Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. |
| latest_version_id | string | ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. |
| source | object | Where the Skill comes from. Possible values: - `"custom"`: authored by the platform user; private to their workspace - `"anthropic"`: published by Anthropic; shared and read-only - `"anthropic_example"`: Anthropic-published sample Skill - `"plugin"`: resolved from an installed plugin |
| source.type | string | Where the Skill comes from. Possible values: - `"custom"`: authored by the platform user; private to their workspace - `"anthropic"`: published by Anthropic; shared and read-only - `"anthropic_example"`: Anthropic-published sample Skill - `"plugin"`: resolved from an installed plugin |
| type | string | Object type. For Skills, this is always `"skill"`. |
| updated_at | string | ISO 8601 timestamp of when the skill was last updated. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| type | string | Deleted object type. For Skills, this is always `"skill_deleted"`. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| created_at | string | ISO 8601 timestamp of when the skill was created. |
| display_name | string | Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. |
| latest_version_id | string | ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. |
| source | object | Where the Skill comes from. Possible values: - `"custom"`: authored by the platform user; private to their workspace - `"anthropic"`: published by Anthropic; shared and read-only - `"anthropic_example"`: Anthropic-published sample Skill - `"plugin"`: resolved from an installed plugin |
| source.type | string | Where the Skill comes from. Possible values: - `"custom"`: authored by the platform user; private to their workspace - `"anthropic"`: published by Anthropic; shared and read-only - `"anthropic_example"`: Anthropic-published sample Skill - `"plugin"`: resolved from an installed plugin |
| type | string | Object type. For Skills, this is always `"skill"`. |
| updated_at | string | ISO 8601 timestamp of when the skill was last updated. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. |
| data[].created_at | string | ISO 8601 timestamp of when the skill was created. |
| data[].description | string | Description of the skill version. This is extracted from the SKILL.md file in the skill upload. |
| data[].name | string | The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. |
| data[].skill_id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| data[].type | string | Object type. For Skill Versions, this is always `"skill_version"`. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**multipart/form-data**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. |
| created_at | string | ISO 8601 timestamp of when the skill was created. |
| description | string | Description of the skill version. This is extracted from the SKILL.md file in the skill upload. |
| name | string | The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. |
| skill_id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| type | string | Object type. For Skill Versions, this is always `"skill_version"`. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. |
| type | string | Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. |
| created_at | string | ISO 8601 timestamp of when the skill was created. |
| description | string | Description of the skill version. This is extracted from the SKILL.md file in the skill upload. |
| name | string | The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. |
| skill_id | string | Unique identifier for the skill. The format and length of IDs may change over time. |
| type | string | Object type. For Skill Versions, this is always `"skill_version"`. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Binary response body
**application/octet-stream**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | string (binary) | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the tunnel, prefixed with `tnl_`. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].display_name | null | string | Human-readable name for the tunnel (1-255 characters). Null if unset. |
| data[].domain | string | Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. |
| data[].type | string | |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the tunnel, prefixed with `tnl_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | null | string | Human-readable name for the tunnel (1-255 characters). Null if unset. |
| domain | string | Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the tunnel, prefixed with `tnl_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | null | string | Human-readable name for the tunnel (1-255 characters). Null if unset. |
| domain | string | Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the tunnel, prefixed with `tnl_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | null | string | Human-readable name for the tunnel (1-255 characters). Null if unset. |
| domain | string | Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the certificate, prefixed with `tcrt_`. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].expires_at | null | string | A timestamp in RFC 3339 format |
| data[].fingerprint | string | Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. |
| data[].tunnel_id | string | ID of the tunnel the certificate is registered against. |
| data[].type | string | |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the certificate, prefixed with `tcrt_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| expires_at | null | string | A timestamp in RFC 3339 format |
| fingerprint | string | Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. |
| tunnel_id | string | ID of the tunnel the certificate is registered against. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the certificate, prefixed with `tcrt_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| expires_at | null | string | A timestamp in RFC 3339 format |
| fingerprint | string | Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. |
| tunnel_id | string | ID of the tunnel the certificate is registered against. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the certificate, prefixed with `tcrt_`. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| expires_at | null | string | A timestamp in RFC 3339 format |
| fingerprint | string | Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. |
| tunnel_id | string | ID of the tunnel the certificate is registered against. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Stable identifier for the current token value. Changes when the token is rotated. |
| tunnel_token | string | The connector token used to run the tunnel. Treat as a credential. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Stable identifier for the current token value. Changes when the token is rotated. |
| tunnel_token | string | The connector token used to run the tunnel. Treat as a credential. |
| type | string | |
# 列出凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the vault. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].display_name | string | Human-readable name for the vault. |
| data[].metadata | object | Arbitrary key-value metadata attached to the vault. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| next_page | string | null | |
# 创建凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the vault. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | string | Human-readable name for the vault. |
| metadata | object | Arbitrary key-value metadata attached to the vault. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
# 删除凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier of the deleted vault. |
| type | string | |
# 读取凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the vault. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | string | Human-readable name for the vault. |
| metadata | object | Arbitrary key-value metadata attached to the vault. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
# 更新凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the vault. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | string | Human-readable name for the vault. |
| metadata | object | Arbitrary key-value metadata attached to the vault. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
# 归档凭据库
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the vault. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| created_at | string | A timestamp in RFC 3339 format |
| display_name | string | Human-readable name for the vault. |
| metadata | object | Arbitrary key-value metadata attached to the vault. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | |
| data[].id | string | Unique identifier for the credential. |
| data[].archived_at | null | string | A timestamp in RFC 3339 format |
| data[].auth | object | Authentication details for a credential. |
| data[].created_at | string | A timestamp in RFC 3339 format |
| data[].metadata | object | Arbitrary key-value metadata attached to the credential. |
| data[].type | string | |
| data[].updated_at | string | A timestamp in RFC 3339 format |
| data[].vault_id | string | Identifier of the vault this credential belongs to. |
| data[].display_name | null | string | Human-readable name for the credential. |
| next_page | string | null | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the credential. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| auth | object | Authentication details for a credential. |
| auth.mcp_server_url | string | URL of the MCP server this credential authenticates against. |
| auth.type | string | |
| auth.expires_at | null | string | A timestamp in RFC 3339 format |
| auth.refresh | null | object | OAuth refresh token configuration returned in credential responses. |
| auth.injection_location | object | Where in the outbound request the secret value is substituted. |
| auth.networking | object | Outbound hosts the secret value is substituted on. |
| auth.secret_name | string | Name of the environment variable. |
| created_at | string | A timestamp in RFC 3339 format |
| metadata | object | Arbitrary key-value metadata attached to the credential. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_id | string | Identifier of the vault this credential belongs to. |
| display_name | null | string | Human-readable name for the credential. |
## MCP OAuth 创建限制 [#mcp-oauth-创建限制]
上面的示例创建 environment\_variable 凭据。创建 mcp\_oauth 仍返回 501，不会创建凭据；更新已有 mcp\_oauth 凭据也不支持。以下为创建请求的实测错误响应。
```json
{
"type": "error",
"error": {
"type": "not_implemented_error",
"message": "Not implemented: creating mcp_oauth credentials is not available on this platform yet; use static_bearer or environment_variable."
},
"request_id": "4c1dcdba-97bb-46ce-aad0-0a7d8753357c"
}
```
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier of the deleted credential. |
| type | string | |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the credential. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| auth | object | Authentication details for a credential. |
| auth.mcp_server_url | string | URL of the MCP server this credential authenticates against. |
| auth.type | string | |
| auth.expires_at | null | string | A timestamp in RFC 3339 format |
| auth.refresh | null | object | OAuth refresh token configuration returned in credential responses. |
| auth.injection_location | object | Where in the outbound request the secret value is substituted. |
| auth.networking | object | Outbound hosts the secret value is substituted on. |
| auth.secret_name | string | Name of the environment variable. |
| created_at | string | A timestamp in RFC 3339 format |
| metadata | object | Arbitrary key-value metadata attached to the credential. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_id | string | Identifier of the vault this credential belongs to. |
| display_name | null | string | Human-readable name for the credential. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the credential. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| auth | object | Authentication details for a credential. |
| auth.mcp_server_url | string | URL of the MCP server this credential authenticates against. |
| auth.type | string | |
| auth.expires_at | null | string | A timestamp in RFC 3339 format |
| auth.refresh | null | object | OAuth refresh token configuration returned in credential responses. |
| auth.injection_location | object | Where in the outbound request the secret value is substituted. |
| auth.networking | object | Outbound hosts the secret value is substituted on. |
| auth.secret_name | string | Name of the environment variable. |
| created_at | string | A timestamp in RFC 3339 format |
| metadata | object | Arbitrary key-value metadata attached to the credential. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_id | string | Identifier of the vault this credential belongs to. |
| display_name | null | string | Human-readable name for the credential. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Unique identifier for the credential. |
| archived_at | null | string | A timestamp in RFC 3339 format |
| auth | object | Authentication details for a credential. |
| auth.mcp_server_url | string | URL of the MCP server this credential authenticates against. |
| auth.type | string | |
| auth.expires_at | null | string | A timestamp in RFC 3339 format |
| auth.refresh | null | object | OAuth refresh token configuration returned in credential responses. |
| auth.injection_location | object | Where in the outbound request the secret value is substituted. |
| auth.networking | object | Outbound hosts the secret value is substituted on. |
| auth.secret_name | string | Name of the environment variable. |
| created_at | string | A timestamp in RFC 3339 format |
| metadata | object | Arbitrary key-value metadata attached to the credential. |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| vault_id | string | Identifier of the vault this credential belongs to. |
| display_name | null | string | Human-readable name for the credential. |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| credential_id | string | Unique identifier of the credential that was validated. |
| has_refresh_token | boolean | Whether the credential has a refresh token configured. |
| mcp_probe | null | object | The failing step of an MCP validation probe. |
| mcp_probe.http_response | null | object | An HTTP response captured during a credential validation probe. |
| mcp_probe.method | string | The MCP method that failed (for example `initialize` or `tools/list`). |
| refresh | null | object | Outcome of a refresh-token exchange attempted during credential validation. |
| refresh.http_response | null | object | An HTTP response captured during a credential validation probe. |
| refresh.status | string | Outcome of a refresh-token exchange attempted during credential validation. - `succeeded` - The token endpoint returned a new access token. - `failed` - The token endpoint returned an error response. See `http_response` for detail. - `connect_error` - The token endpoint could not be reached (DNS, TLS, or connection error). - `no_refresh_token` - No refresh token is stored for the credential, so no exchange was attempted. |
| status | string | Overall verdict of a credential validation probe. |
| type | string | |
| validated_at | string | A timestamp in RFC 3339 format |
| vault_id | string | Identifier of the vault containing the credential. |
## 示例前提 [#示例前提]
此示例针对前面创建的 static 凭据，因此实测返回 400 invalid\_request\_error。要获得校验结果，请先通过[一键授权](/docs/api/native/vault/authorizations)完成用户授权，再将 credential\_id 换成产生的 OAuth Secret ID。校验 OAuth 凭据返回 HTTP 200，状态为 valid、invalid 或 unknown。
# Google Gemini 兼容接口
## 基础地址 [#基础地址]
## 接入 [#接入]
## 可用模型 [#可用模型]
* 路径里的模型名就是平台模型名（如 `gemini-2.5-flash`），可用模型见[列出模型](/docs/api/compatible/google/listModels)。只有声明了 Google 协议的模型可以在这里调用，其他模型返回 404。
* 需要图片输出时，在 `generationConfig.responseModalities` 里带上 `IMAGE`，请求会交给平台的图像模型处理。
* 在思考模型上强制调用工具（`toolConfig` 的 `ANY` 模式）与 Gemini 原生 API 一致，会原样转发给模型：模型接受即执行，不接受时返回 Google 格式的 400 错误。
## 端点 [#端点]
| 方法 | 路径 | 说明 | 支持 |
| ---- | ------------------------------------------------------------------------------------------------------ | -------- | ------ |
| POST | [`/v1beta/models/{modelsId}:generateContent`](/docs/api/compatible/google/generateContent) | 生成内容 | ● 支持 |
| POST | [`/v1beta/models/{modelsId}:streamGenerateContent`](/docs/api/compatible/google/streamGenerateContent) | 流式生成内容 | ● 支持 |
| POST | [`/v1beta/models/{modelsId}:countTokens`](/docs/api/compatible/google/countTokens) | 统计 token | ◐ 部分支持 |
| POST | [`/v1beta/models/{modelsId}:embedContent`](/docs/api/compatible/google/embedContent) | 生成向量嵌入 | ● 支持 |
| POST | [`/v1beta/models/{modelsId}:batchEmbedContents`](/docs/api/compatible/google/batchEmbedContents) | 批量生成向量嵌入 | ● 支持 |
| GET | [`/v1beta/models`](/docs/api/compatible/google/listModels) | 列出模型 | ● 支持 |
| GET | [`/v1beta/models/{modelsId}`](/docs/api/compatible/google/getModel) | 读取模型 | ● 支持 |
## 与官方的差异 [#与官方的差异]
* 生成内容：toolConfig 的强制工具（functionCallingConfig mode ANY，含 allowedFunctionNames） 在思考模型上同样忠实转发给上游——与 Gemini 原生 API 一致，是否接受由上游模型 决定：如果上游返回 400，错误保持 Google 格式并携带上游的代码与状态。
* 统计 token：按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。
* 生成向量嵌入：只接受文本部件；图像等多模态部件会被拒绝。taskType、title 以及 autoTruncate / documentOcr / audioTrackExtraction 等检索配置在平台上没有等价语义， 请求携带时会收到 400（INVALID\_ARGUMENT），不会静默忽略——因为不同 taskType 生成的向量行为不同，静默丢弃会悄悄改变检索质量。outputDimensionality 映射为 返回向量的维度。
* 批量生成向量嵌入：requests 中每一项的约束与 embedContent 相同（文本部件、同上拒绝规则）；批量内 所有条目的 outputDimensionality 必须一致。当前官方 JS 与 Python SDK 的 embedContent 调用实际走的就是这个批量端点。
* 列出模型：向量嵌入模型会以 embedContent 作为其唯一受支持的方法列出。当模型目录 暂时不可用时，generateContent 的行为保持不变：显式要求图像输出 （responseModalities 含 IMAGE）的请求仍走图像通道；未显式声明的旧式图像请求 在该窗口内会按文本对话处理——降级期间每个响应都带 X-Praxis-Route-Degraded: model-catalog-unavailable 头以示区别。
参数与字段的权威定义以 [Gemini API 官方文档](https://ai.google.dev/api)为准。
错误按 Gemini API 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
# 生成内容
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| candidates | array<object> | Candidate responses from the model. |
| candidates[].avgLogprobs | number | Output only. Average log probability score of the candidate. |
| candidates[].citationMetadata | object | Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data. |
| candidates[].content | object | Output only. Generated content returned from the model. |
| candidates[].finishMessage | string | Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set. |
| candidates[].finishReason | string | Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens. |
| candidates[].groundingAttributions | array<object> | Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls. |
| candidates[].groundingMetadata | object | Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls. |
| candidates[].index | integer | Output only. Index of the candidate in the list of response candidates. |
| candidates[].logprobsResult | object | Output only. Log-likelihood scores for the response tokens and top tokens |
| candidates[].safetyRatings | array<object> | List of ratings for the safety of a response candidate. There is at most one rating per category. |
| candidates[].tokenCount | integer | Output only. Token count for this candidate. |
| candidates[].urlContextMetadata | object | Output only. Metadata related to url context retrieval tool. |
| modelStatus | object | Output only. The current model status of this model. |
| modelStatus.message | string | A message explaining the model status. |
| modelStatus.modelStage | string | The stage of the underlying model. |
| modelStatus.retirementTime | string | The time at which the model will be retired. |
| modelVersion | string | Output only. The model version used to generate the response. |
| promptFeedback | object | Returns the prompt's feedback related to the content filters. |
| promptFeedback.blockReason | string | Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt. |
| promptFeedback.safetyRatings | array<object> | Ratings for safety of the prompt. There is at most one rating per category. |
| responseId | string | Output only. response_id is used to identify each response. |
| usageMetadata | object | Output only. Metadata on the generation requests' token usage. |
| usageMetadata.cacheTokensDetails | array<object> | Output only. List of modalities of the cached content in the request input. |
| usageMetadata.cachedContentTokenCount | integer | Number of tokens in the cached part of the prompt (the cached content) |
| usageMetadata.candidatesTokenCount | integer | Total number of tokens across all the generated response candidates. |
| usageMetadata.candidatesTokensDetails | array<object> | Output only. List of modalities that were returned in the response. |
| usageMetadata.promptTokenCount | integer | Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content. |
| usageMetadata.promptTokensDetails | array<object> | Output only. List of modalities that were processed in the request input. |
| usageMetadata.serviceTier | string | Output only. Service tier of the request. |
| usageMetadata.thoughtsTokenCount | integer | Output only. Number of tokens of thoughts for thinking models. |
| usageMetadata.toolUsePromptTokenCount | integer | Output only. Number of tokens present in tool-use prompt(s). |
| usageMetadata.toolUsePromptTokensDetails | array<object> | Output only. List of modalities that were processed for tool-use request inputs. |
| usageMetadata.totalTokenCount | integer | Total token count for the generation request (prompt + thoughts + response candidates). |
# 流式生成内容
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| candidates | array<object> | Candidate responses from the model. |
| candidates[].avgLogprobs | number | Output only. Average log probability score of the candidate. |
| candidates[].citationMetadata | object | Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data. |
| candidates[].content | object | Output only. Generated content returned from the model. |
| candidates[].finishMessage | string | Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set. |
| candidates[].finishReason | string | Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens. |
| candidates[].groundingAttributions | array<object> | Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls. |
| candidates[].groundingMetadata | object | Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls. |
| candidates[].index | integer | Output only. Index of the candidate in the list of response candidates. |
| candidates[].logprobsResult | object | Output only. Log-likelihood scores for the response tokens and top tokens |
| candidates[].safetyRatings | array<object> | List of ratings for the safety of a response candidate. There is at most one rating per category. |
| candidates[].tokenCount | integer | Output only. Token count for this candidate. |
| candidates[].urlContextMetadata | object | Output only. Metadata related to url context retrieval tool. |
| modelStatus | object | Output only. The current model status of this model. |
| modelStatus.message | string | A message explaining the model status. |
| modelStatus.modelStage | string | The stage of the underlying model. |
| modelStatus.retirementTime | string | The time at which the model will be retired. |
| modelVersion | string | Output only. The model version used to generate the response. |
| promptFeedback | object | Returns the prompt's feedback related to the content filters. |
| promptFeedback.blockReason | string | Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt. |
| promptFeedback.safetyRatings | array<object> | Ratings for safety of the prompt. There is at most one rating per category. |
| responseId | string | Output only. response_id is used to identify each response. |
| usageMetadata | object | Output only. Metadata on the generation requests' token usage. |
| usageMetadata.cacheTokensDetails | array<object> | Output only. List of modalities of the cached content in the request input. |
| usageMetadata.cachedContentTokenCount | integer | Number of tokens in the cached part of the prompt (the cached content) |
| usageMetadata.candidatesTokenCount | integer | Total number of tokens across all the generated response candidates. |
| usageMetadata.candidatesTokensDetails | array<object> | Output only. List of modalities that were returned in the response. |
| usageMetadata.promptTokenCount | integer | Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content. |
| usageMetadata.promptTokensDetails | array<object> | Output only. List of modalities that were processed in the request input. |
| usageMetadata.serviceTier | string | Output only. Service tier of the request. |
| usageMetadata.thoughtsTokenCount | integer | Output only. Number of tokens of thoughts for thinking models. |
| usageMetadata.toolUsePromptTokenCount | integer | Output only. Number of tokens present in tool-use prompt(s). |
| usageMetadata.toolUsePromptTokensDetails | array<object> | Output only. List of modalities that were processed for tool-use request inputs. |
| usageMetadata.totalTokenCount | integer | Total token count for the generation request (prompt + thoughts + response candidates). |
#
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| cacheTokensDetails | array<object> | Output only. List of modalities that were processed in the cached content. |
| cacheTokensDetails[].modality | string | The modality associated with this token count. |
| cacheTokensDetails[].tokenCount | integer | Number of tokens. |
| cachedContentTokenCount | integer | Number of tokens in the cached part of the prompt (the cached content). |
| promptTokensDetails | array<object> | Output only. List of modalities that were processed in the request input. |
| promptTokensDetails[].modality | string | The modality associated with this token count. |
| promptTokensDetails[].tokenCount | integer | Number of tokens. |
| totalTokens | integer | The number of tokens that the `Model` tokenizes the `prompt` into. Always non-negative. |
# 生成向量嵌入
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| embedding | object | Output only. The embedding generated from the input content. |
| embedding.shape | array<integer> | This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]). |
| embedding.values | array<number> | The embedding values. This is for 3P users only and will not be populated for 1P calls. |
| usageMetadata | object | Output only. The usage metadata for the request. |
| usageMetadata.promptTokenCount | integer | Output only. Number of tokens in the prompt. |
| usageMetadata.promptTokenDetails | array<object> | Output only. List of modalities that were processed in the request input. |
# 批量生成向量嵌入
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| embeddings | array<object> | Output only. The embeddings for each request, in the same order as provided in the batch request. |
| embeddings[].shape | array<integer> | This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]). |
| embeddings[].values | array<number> | The embedding values. This is for 3P users only and will not be populated for 1P calls. |
| usageMetadata | object | Output only. The usage metadata for the request. |
| usageMetadata.promptTokenCount | integer | Output only. Number of tokens in the prompt. |
| usageMetadata.promptTokenDetails | array<object> | Output only. List of modalities that were processed in the request input. |
# 列出模型
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| models | array<object> | The returned Models. |
| models[].baseModelId | string | Required. The name of the base model, pass this to the generation request. Examples: * `gemini-1.5-flash` |
| models[].description | string | A short description of the model. |
| models[].displayName | string | The human-readable name of the model. E.g. "Gemini 1.5 Flash". The name can be up to 128 characters long and can consist of any UTF-8 characters. |
| models[].inputTokenLimit | integer | Maximum number of input tokens allowed for this model. |
| models[].maxTemperature | number | The maximum temperature this model can use. |
| models[].name | string | Required. The resource name of the `Model`. Refer to [Model variants](https://ai.google.dev/gemini-api/docs/models/gemini#model-variations) for all allowed values. Format: `models/{model}` with a `{model}` naming convention of: * "{base_model_id}-{version}" Examples: * `models/gemini-1.5-flash-001` |
| models[].outputTokenLimit | integer | Maximum number of output tokens available for this model. |
| models[].supportedGenerationMethods | array<string> | The model's supported generation methods. The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`. |
| models[].temperature | number | Controls the randomness of the output. Values can range over `[0.0,max_temperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model. |
| models[].thinking | boolean | Whether the model supports thinking. |
| models[].topK | integer | For Top-k sampling. Top-k sampling considers the set of `top_k` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `top_k` isn't allowed as a generation parameter. |
| models[].topP | number | For [Nucleus sampling](https://ai.google.dev/gemini-api/docs/prompting-strategies#top-p). Nucleus sampling considers the smallest set of tokens whose probability sum is at least `top_p`. This value specifies default to be used by the backend while making the call to the model. |
| models[].version | string | Required. The version number of the model. This represents the major version (`1.0` or `1.5`) |
| nextPageToken | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no more pages. |
# 读取模型
## 响应 [#响应]
### HTTP 200 [#http-200]
Successful response
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| baseModelId | string | Required. The name of the base model, pass this to the generation request. Examples: * `gemini-1.5-flash` |
| description | string | A short description of the model. |
| displayName | string | The human-readable name of the model. E.g. "Gemini 1.5 Flash". The name can be up to 128 characters long and can consist of any UTF-8 characters. |
| inputTokenLimit | integer | Maximum number of input tokens allowed for this model. |
| maxTemperature | number | The maximum temperature this model can use. |
| name | string | Required. The resource name of the `Model`. Refer to [Model variants](https://ai.google.dev/gemini-api/docs/models/gemini#model-variations) for all allowed values. Format: `models/{model}` with a `{model}` naming convention of: * "{base_model_id}-{version}" Examples: * `models/gemini-1.5-flash-001` |
| outputTokenLimit | integer | Maximum number of output tokens available for this model. |
| supportedGenerationMethods | array<string> | The model's supported generation methods. The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`. |
| temperature | number | Controls the randomness of the output. Values can range over `[0.0,max_temperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model. |
| thinking | boolean | Whether the model supports thinking. |
| topK | integer | For Top-k sampling. Top-k sampling considers the set of `top_k` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `top_k` isn't allowed as a generation parameter. |
| topP | number | For [Nucleus sampling](https://ai.google.dev/gemini-api/docs/prompting-strategies#top-p). Nucleus sampling considers the smallest set of tokens whose probability sum is at least `top_p`. This value specifies default to be used by the backend while making the call to the model. |
| version | string | Required. The version number of the model. This represents the major version (`1.0` or `1.5`) |
# E2B 兼容接口
## 基础地址 [#基础地址]
## 接入 [#接入]
## 控制面与数据面 [#控制面与数据面]
* **控制面**：创建、列出、暂停、连接、终止沙箱等本页列出的端点，地址是上面的基础地址，用你的 API Key 认证（`X-API-Key` 头，官方 SDK 自动带上）。
* **数据面**：在沙箱里运行命令、读写文件，由 SDK 直连 `<端口>-<沙箱 ID>.praxisusercontent.com`，用创建沙箱时返回的访问凭证认证。所以 SDK 除了 `api_url` 还要把 `domain` 设为 `praxisusercontent.com`。
也可以不改代码，只设环境变量：
## 端点 [#端点]
| 方法 | 路径 | 说明 | 支持 |
| ------ | --------------------------------------------------------------------------------- | -------- | ---- |
| POST | [`/sandboxes`](/docs/api/compatible/e2b/createSandbox) | 创建沙箱 | ● 支持 |
| GET | [`/sandboxes`](/docs/api/compatible/e2b/listSandboxes) | 列出沙箱 | ● 支持 |
| GET | [`/sandboxes/{sandboxID}`](/docs/api/compatible/e2b/getSandbox) | 读取沙箱 | ● 支持 |
| GET | [`/sandboxes/{sandboxID}/metrics`](/docs/api/compatible/e2b/getSandboxMetrics) | 沙箱指标 | ● 支持 |
| POST | [`/sandboxes/{sandboxID}/timeout`](/docs/api/compatible/e2b/setSandboxTimeout) | 设置超时 | ● 支持 |
| POST | [`/sandboxes/{sandboxID}/pause`](/docs/api/compatible/e2b/pauseSandbox) | 暂停沙箱 | ● 支持 |
| POST | [`/sandboxes/{sandboxID}/connect`](/docs/api/compatible/e2b/connectSandbox) | 连接沙箱 | ● 支持 |
| DELETE | [`/sandboxes/{sandboxID}`](/docs/api/compatible/e2b/killSandbox) | 终止沙箱 | ● 支持 |
| POST | [`/v2/sandboxes`](/docs/api/compatible/e2b/createSandboxV2) | 创建沙箱（v2） | ● 支持 |
| GET | [`/v2/sandboxes`](/docs/api/compatible/e2b/listSandboxesV2) | 列出沙箱（v2） | ● 支持 |
| POST | [`/v2/sandboxes/{sandboxID}/connect`](/docs/api/compatible/e2b/connectSandboxV2) | 连接沙箱（v2） | ● 支持 |
| GET | [`/templates`](/docs/api/compatible/e2b/listTemplates) | 列出模板 | ● 支持 |
| GET | [`/v2/templates`](/docs/api/compatible/e2b/listTemplatesV2) | 列出模板（v2） | ● 支持 |
| POST | [`/volumes`](/docs/api/compatible/e2b/createVolume) | 创建卷 | ● 支持 |
| GET | [`/volumes`](/docs/api/compatible/e2b/listVolumes) | 列出卷 | ● 支持 |
| GET | [`/volumes/{volumeID}`](/docs/api/compatible/e2b/getVolume) | 读取卷 | ● 支持 |
| DELETE | [`/volumes/{volumeID}`](/docs/api/compatible/e2b/deleteVolume) | 删除卷 | ● 支持 |
| POST | [`/sandboxes/{sandboxID}/fork`](/docs/api/compatible/e2b/forkSandbox) | 复制沙箱 | ● 支持 |
| POST | [`/sandboxes/{sandboxID}/snapshots`](/docs/api/compatible/e2b/createSnapshot) | 创建快照 | ● 支持 |
| GET | [`/snapshots`](/docs/api/compatible/e2b/listSnapshots) | 列出快照 | ● 支持 |
| DELETE | [`/templates/{templateID}`](/docs/api/compatible/e2b/deleteSnapshot) | 删除快照 | ● 支持 |
| PUT | [`/sandboxes/{sandboxID}/network`](/docs/api/compatible/e2b/updateSandboxNetwork) | 更新网络策略 | ● 支持 |
| GET | [`/v2/sandboxes/{sandboxID}/logs`](/docs/api/compatible/e2b/getSandboxLogs) | 读取沙箱日志 | ● 支持 |
## 与官方的差异 [#与官方的差异]
* 创建沙箱：已弃用：最新官方 SDK 走 v2。平台暂未提供 E2B 默认的 base 模板：不带模板参数的 Sandbox.create() 会返回 404，请显式指定模板（可用模板见「列出模板」）。
* 列出沙箱：已弃用：最新官方 SDK 走 v2。
* 连接沙箱：已弃用：最新官方 SDK 走 v2。
* 列出模板：已弃用：最新官方 SDK 走 v2。
参数与字段的权威定义以 [E2B 官方文档](https://docs.e2b.dev/api-reference)为准。
错误按 E2B 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
# 创建沙箱
## 响应 [#响应]
### HTTP 201 [#http-201]
The sandbox was created successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
# 列出沙箱
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned all running sandboxes
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].templateID | string | Identifier of the template from which is the sandbox created |
| [].alias | string | Alias of the template |
| [].sandboxID | string | Identifier of the sandbox |
| [].clientID | string | Identifier of the client |
| [].startedAt | string | Time when the sandbox was started |
| [].endAt | string | Time when the sandbox will expire |
| [].cpuCount | integer | CPU cores for the sandbox |
| [].memoryMB | integer | Memory for the sandbox in MiB |
| [].diskSizeMB | integer | Disk size for the sandbox in MiB |
| [].metadata | any | |
| [].state | string | State of the sandbox |
| [].envdVersion | string | Version of the envd running in the sandbox |
| [].volumeMounts | array<object> | |
| [].volumeMounts[].name | string | Name of the volume |
| [].volumeMounts[].path | string | Path of the volume |
# 读取沙箱
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned the sandbox
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| alias | string | Alias of the template |
| sandboxID | string | Identifier of the sandbox |
| clientID | string | Identifier of the client |
| startedAt | string | Time when the sandbox was started |
| endAt | string | Time when the sandbox will expire |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| allowInternetAccess | boolean | Whether internet access was explicitly enabled or disabled for the sandbox. Null means it was not explicitly set. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
| cpuCount | integer | CPU cores for the sandbox |
| memoryMB | integer | Memory for the sandbox in MiB |
| diskSizeMB | integer | Disk size for the sandbox in MiB |
| metadata | any | |
| state | string | State of the sandbox |
| network | object | |
| network.allowPublicTraffic | boolean | Specify if the sandbox URLs should be accessible only with authentication. |
| network.allowOut | array<string> | List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. |
| network.denyOut | array<string> | List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules. |
| network.egressProxy | object | SOCKS5 proxy for sandbox egress. Outbound TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use remote DNS (ATYP=domain). |
| network.maskRequestHost | string | Specify host mask which will be used for all sandbox requests |
| network.httpsPorts | array<integer> | Unlike E2B, network.httpsPorts is rejected; omit it and serve plaintext HTTP inside the sandbox. The public port URL still uses HTTPS. The upstream field denotes HTTPS-speaking internal ports, permits self-signed certificates and excludes envd port 49983. |
| network.rules | object | Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination. |
| lifecycle | object | Sandbox lifecycle policy returned by sandbox info. |
| lifecycle.autoResume | boolean | Whether the sandbox can auto-resume. |
| lifecycle.onTimeout | string | Action taken when the sandbox times out. |
| volumeMounts | array<object> | |
| volumeMounts[].name | string | Name of the volume |
| volumeMounts[].path | string | Path of the volume |
# 沙箱指标
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned the sandbox metrics
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].timestamp | string | Timestamp of the metric entry |
| [].timestampUnix | integer | Timestamp of the metric entry in Unix time (seconds since epoch) |
| [].cpuCount | integer | Number of CPU cores |
| [].cpuUsedPct | number | CPU usage percentage |
| [].memUsed | integer | Memory used in bytes |
| [].memTotal | integer | Total memory in bytes |
| [].memCache | integer | Cached memory (page cache) in bytes |
| [].diskUsed | integer | Disk used in bytes |
| [].diskTotal | integer | Total disk space in bytes |
# 设置超时
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 204 [#http-204]
Successfully set the sandbox timeout
未声明响应体。
# 暂停沙箱
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 204 [#http-204]
The sandbox was paused successfully and can be resumed
未声明响应体。
# 连接沙箱
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The sandbox was already running
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
### HTTP 201 [#http-201]
The sandbox was resumed successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
# 终止沙箱
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 204 [#http-204]
The sandbox was killed successfully
未声明响应体。
# 创建沙箱（v2）
## 响应 [#响应]
### HTTP 201 [#http-201]
The sandbox was created successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
# 列出沙箱（v2）
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned all running sandboxes
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].templateID | string | Identifier of the template from which is the sandbox created |
| [].alias | string | Alias of the template |
| [].sandboxID | string | Identifier of the sandbox |
| [].clientID | string | Identifier of the client |
| [].startedAt | string | Time when the sandbox was started |
| [].endAt | string | Time when the sandbox will expire |
| [].cpuCount | integer | CPU cores for the sandbox |
| [].memoryMB | integer | Memory for the sandbox in MiB |
| [].diskSizeMB | integer | Disk size for the sandbox in MiB |
| [].metadata | any | |
| [].state | string | State of the sandbox |
| [].envdVersion | string | Version of the envd running in the sandbox |
| [].volumeMounts | array<object> | |
| [].volumeMounts[].name | string | Name of the volume |
| [].volumeMounts[].path | string | Path of the volume |
# 连接沙箱（v2）
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
The sandbox was already running
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
### HTTP 201 [#http-201]
The sandbox was resumed successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| templateID | string | Identifier of the template from which is the sandbox created |
| sandboxID | string | Identifier of the sandbox |
| alias | string | Alias of the template |
| clientID | string | Identifier of the client |
| envdVersion | string | Version of the envd running in the sandbox |
| envdAccessToken | string | Access token used for envd communication |
| trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
# 列出模板
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned all templates
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].templateID | string | Identifier of the template |
| [].buildID | string | Identifier of the last successful build for given template |
| [].cpuCount | integer | CPU cores for the sandbox |
| [].memoryMB | integer | Memory for the sandbox in MiB |
| [].diskSizeMB | integer | Disk size for the sandbox in MiB |
| [].public | boolean | Whether the template is public or only accessible by the team |
| [].aliases | array<string> | Aliases of the template |
| [].names | array<string> | Names of the template (namespace/alias format when namespaced) |
| [].createdAt | string | Time when the template was created |
| [].updatedAt | string | Time when the template was last updated |
| [].createdBy | object | |
| [].createdBy.id | string | Identifier of the user |
| [].createdBy.email | string | Email of the user |
| [].lastSpawnedAt | string | Time when the template was last used |
| [].spawnCount | integer | Number of times the template was used |
| [].buildCount | integer | Number of times the template was built |
| [].envdVersion | string | Version of the envd running in the sandbox |
| [].buildStatus | string | Status of the template build |
# 列出模板（v2）
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned all templates
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].templateID | string | Identifier of the template |
| [].buildID | string | Identifier of the last successful build for given template |
| [].cpuCount | integer | CPU cores for the sandbox |
| [].memoryMB | integer | Memory for the sandbox in MiB |
| [].diskSizeMB | integer | Disk size for the sandbox in MiB |
| [].public | boolean | Whether the template is public or only accessible by the team |
| [].aliases | array<string> | Aliases of the template |
| [].names | array<string> | Names of the template (namespace/alias format when namespaced) |
| [].createdAt | string | Time when the template was created |
| [].updatedAt | string | Time when the template was last updated |
| [].createdBy | object | |
| [].createdBy.id | string | Identifier of the user |
| [].createdBy.email | string | Email of the user |
| [].lastSpawnedAt | string | Time when the template was last used |
| [].spawnCount | integer | Number of times the template was used |
| [].buildCount | integer | Number of times the template was built |
| [].envdVersion | string | Version of the envd running in the sandbox |
| [].buildStatus | string | Status of the template build |
# 创建卷
## 响应 [#响应]
### HTTP 201 [#http-201]
Successfully created a new team volume
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| volumeID | string | ID of the volume |
| name | string | Name of the volume |
| token | string | Auth token to use for interacting with volume content |
| domain | string | Domain to use as the destination for volume content requests, replacing the default `api.<E2B_DOMAIN>`. Only returned when the team is connected to a custom (BYOC) cluster; absent otherwise, in which case the default domain is used. |
# 列出卷
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully listed all team volumes
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].volumeID | string | ID of the volume |
| [].name | string | Name of the volume |
# 读取卷
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully retrieved a team volume
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| volumeID | string | ID of the volume |
| name | string | Name of the volume |
| token | string | Auth token to use for interacting with volume content |
| domain | string | Domain to use as the destination for volume content requests, replacing the default `api.<E2B_DOMAIN>`. Only returned when the team is connected to a custom (BYOC) cluster; absent otherwise, in which case the default domain is used. |
# 删除卷
## 响应 [#响应]
### HTTP 204 [#http-204]
Successfully deleted a team volume
未声明响应体。
# 复制沙箱
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 201 [#http-201]
The sandbox was snapshotted and the forks were attempted; each entry reports one fork's outcome
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].sandbox | object | |
| [].sandbox.templateID | string | Identifier of the template from which is the sandbox created |
| [].sandbox.sandboxID | string | Identifier of the sandbox |
| [].sandbox.alias | string | Alias of the template |
| [].sandbox.clientID | string | Identifier of the client |
| [].sandbox.envdVersion | string | Version of the envd running in the sandbox |
| [].sandbox.envdAccessToken | string | Access token used for envd communication |
| [].sandbox.trafficAccessToken | string | Token required for accessing sandbox via proxy. |
| [].sandbox.domain | string | Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix. |
| [].error | object | |
| [].error.code | integer | Error code |
| [].error.error_code | string | Machine-readable semantic error code. Not a closed set; initial values: sandbox_capacity_unavailable, sandbox_placement_timeout, sandbox_no_compatible_node, sandbox_create_failed, internal_server_error. |
| [].error.message | string | Error |
# 创建快照
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 201 [#http-201]
Snapshot created successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| snapshotID | string | Identifier of the snapshot template including the tag. Uses namespace/alias when a name was provided (e.g. team-slug/my-snapshot:default), otherwise falls back to the raw template ID (e.g. abc123:default). |
| names | array<string> | Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2) |
# 列出快照
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned snapshots
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].snapshotID | string | Identifier of the snapshot template including the tag. Uses namespace/alias when a name was provided (e.g. team-slug/my-snapshot:default), otherwise falls back to the raw template ID (e.g. abc123:default). |
| [].names | array<string> | Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2) |
# 删除快照
## 响应 [#响应]
### HTTP 204 [#http-204]
The template was deleted successfully
未声明响应体。
# 更新网络策略
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 204 [#http-204]
Successfully updated the sandbox network configuration
未声明响应体。
# 读取沙箱日志
先调用「创建沙箱」，用返回的 sandboxID 替换 sbx\_123。
## 响应 [#响应]
### HTTP 200 [#http-200]
Successfully returned the sandbox logs
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| logs | array<object> | Sandbox logs structured |
| logs[].timestamp | string | Timestamp of the log entry |
| logs[].message | string | Log message content |
| logs[].level | string | State of the sandbox |
| logs[].fields | object | |
# Tavily 兼容接口
## 基础地址 [#基础地址]
## 接入 [#接入]
## 端点 [#端点]
| 方法 | 路径 | 说明 | 支持 |
| ---- | --------------------------------------------------- | ------ | ---- |
| POST | [`/search`](/docs/api/compatible/tavily/search) | 搜索 | ● 支持 |
| POST | [`/extract`](/docs/api/compatible/tavily/extract) | 提取网页内容 | ● 支持 |
| POST | [`/crawl`](/docs/api/compatible/tavily/crawl) | 站内爬取 | ● 支持 |
| POST | [`/map`](/docs/api/compatible/tavily/map) | 站点地图 | ● 支持 |
| POST | [`/feedback`](/docs/api/compatible/tavily/feedback) | 提交反馈 | ● 支持 |
## 与官方的差异 [#与官方的差异]
* 站内爬取：调用前要求账户余额大于 0；按 Tavily 返回的 usage.credits 计费，每 credit $0.01；Tavily 未返回用量时，按本次请求可能消耗的上限计费。
* 站点地图：调用前要求账户余额大于 0；按 Tavily 返回的 usage.credits 计费，每 credit $0.01；Tavily 未返回用量时，按本次请求可能消耗的上限计费。
* 提交反馈：原样转发给 Tavily，不计费（Tavily 官方定价未对反馈单独计费）。
参数与字段的权威定义以 [Tavily 官方文档](https://docs.tavily.com/documentation/api-reference)为准。
错误按 Tavily 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。
# 搜索
## 响应 [#响应]
### HTTP 200 [#http-200]
Search results returned successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| query | string | The search query that was executed. |
| answer | string | A short answer to the user's query, generated by an LLM. Included in the response only if `include_answer` is requested (i.e., set to `true`, `basic`, or `advanced`) |
| images | array<object> | A list of query-related images from image search. If `include_image_descriptions` is true, each item will have `url` and `description`. Note: per-result images are also returned inside each result object's `images` field. |
| images[].url | string | |
| images[].description | string | |
| results | array<object> | A list of sorted search results, ranked by relevancy. |
| results[].title | string | The title of the search result. |
| results[].url | string | The URL of the search result. |
| results[].content | string | A short description of the search result. |
| results[].score | number | The relevance score of the search result. |
| results[].raw_content | string | The cleaned and parsed HTML content of the search result. Only if `include_raw_content` is true. |
| results[].published_date | string | Tavily's best estimate of when the source was published or last updated. Can be later than the original publish date. `null` if no date could be detected. Only returned when `include_published_date` is `true` (automatically enabled when `topic` is `news`). |
| results[].favicon | string | The favicon URL for the result. |
| results[].images | array<object> | A list of images extracted from this search result. Only included when `include_images` is `true`. If `include_image_descriptions` is `true`, each item will have `url` and `description`. |
| results[].id | string | Unique identifier for this result |
| auto_parameters | object | A dictionary of the selected auto_parameters, only shown when `auto_parameters` is true. |
| response_time | number | Time in seconds it took to complete the request. |
| usage | object | Credit usage details for the request. |
| request_id | string | A unique request identifier you can share with customer support to help resolve issues with specific requests. |
# 提取网页内容
## 响应 [#响应]
### HTTP 200 [#http-200]
Extraction completed. Check results and failed\_results for each URL. HTTP 200 can have an empty results array when all valid URLs fail during extraction; output order is not guaranteed.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| results | array<object> | A list of extracted content from the provided URLs. |
| results[].url | string | The URL from which the content was extracted. |
| results[].raw_content | string | The full content extracted from the page. When `query` is provided, contains the top-ranked chunks joined by `[...]` separator. |
| results[].images | array<string> | This is only available if `include_images` is set to `true`. A list of image URLs extracted from the page. |
| results[].favicon | string | The favicon URL for the result. |
| failed_results | array<object> | A list of URLs that could not be processed. |
| failed_results[].url | string | The URL that failed to be processed. |
| failed_results[].error | string | An error message describing why the URL couldn't be processed. |
| response_time | number | Time in seconds it took to complete the request. |
| usage | object | Credit usage details for the request. |
| request_id | string | A unique request identifier you can share with customer support to help resolve issues with specific requests. |
# 站内爬取
## 响应 [#响应]
### HTTP 200 [#http-200]
Crawl results returned successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| base_url | string | The base URL that was crawled. |
| results | array<object> | A list of extracted content from the crawled URLs. |
| results[].url | string | The URL that was crawled. |
| results[].raw_content | string | The full content extracted from the page. When `query` is provided, contains the top-ranked chunks joined by `[...]` separator. |
| results[].favicon | string | The favicon URL for the result. |
| response_time | number | Time in seconds it took to complete the request. |
| usage | object | Credit usage details for the request. |
| request_id | string | A unique request identifier you can share with customer support to help resolve issues with specific requests. |
# 站点地图
## 响应 [#响应]
### HTTP 200 [#http-200]
Map results returned successfully
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| base_url | string | The base URL that was mapped. |
| results | array<string> | A list of URLs that were discovered during the mapping. |
| response_time | number | Time in seconds it took to complete the request. |
| usage | object | Credit usage details for the request. |
| request_id | string | A unique request identifier you can share with customer support to help resolve issues with specific requests. |
# 提交反馈
## 响应 [#响应]
### HTTP 200 [#http-200]
Feedback accepted
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Whether the feedback was accepted. |
| feedback_id | string | Unique identifier of this feedback submission. |
| response_time | number | Response time of this feedback request in seconds. |
# Supabase 兼容接口
（待译）
Database exposes its row API through Supabase client paths. Use a base URL ending in /supabase/\/, including the trailing slash, and a Praxis credential. Unlike Supabase, storage uses SQLite; define tables and fields through /database/v1, not SQL migrations, and do not expect Supabase Auth, RLS policies or realtime subscriptions. Auth, storage, realtime, functions and graphql service paths return 501 with x-should-retry=false. See the Database domain for supported concepts and differences.
使用官方 supabase-js 读写一个库中的表。
[指南 →](/docs/cloud/services/database/quickstart)
## 基础地址 [#基础地址]
`https://api.deepraxis.ai/supabase/{database_id}/`
| 部分 | 含义 |
| --- | --- |
| {database_id} | 建库返回的 ID；每个库使用自己的地址。 |
| / | 保留末尾斜杠，supabase-js 才会保留库 ID 并追加 rest/v1。 |
API Key 用作 Authorization: Bearer 凭据；supabase-js 的第二个参数传同一 Key。以下示例在服务端运行。
```typescript
import { createClient } from "@supabase/supabase-js";
const supabase = createClient(
`https://api.deepraxis.ai/supabase/${process.env.DATABASE_ID}/`,
process.env.PRAXIS_API_KEY,
{ auth: { persistSession: false, autoRefreshToken: false } },
);
```
## 表端点 [#表端点]
[GET / HEAD / POST / PATCH / DELETE](/docs/api/compatible/supabase/tables)
`/supabase/{database_id}/rest/v1/{table}`
仅提供下列 PostgREST 子集。不支持的语法返回 HTTP 400，code 为 PGRST127；无效或未知参数可能返回 PGRST100。
## 过滤运算符 [#过滤运算符]
| 值 | 支持情况 |
| --- | --- |
| `eq` | 支持 |
| `neq` | 支持 |
| `gt` | 支持 |
| `gte` | 支持 |
| `lt` | 支持 |
| `lte` | 支持 |
| `like` | 支持 |
| `ilike` | 支持 |
| `in` | 支持 |
| `is` | 支持 |
| `cs` | 支持 |
| `cd` | 支持 |
| `ov` | 支持 |
| `fts` | 不支持 |
| `plfts` | 不支持 |
| `phfts` | 不支持 |
| `wfts` | 不支持 |
| `match` | 不支持 |
| `imatch` | 不支持 |
| `isdistinct` | 不支持 |
| `sl` | 不支持 |
| `sr` | 不支持 |
| `nxl` | 不支持 |
| `nxr` | 不支持 |
| `adj` | 不支持 |
## Prefer [#prefer]
| 值 | 支持情况 |
| --- | --- |
| `return=minimal` | 支持 |
| `return=headers-only` | 支持 |
| `return=representation` | 支持 |
| `count=exact` | 支持 |
| `count=planned` | 部分支持 |
| `count=estimated` | 部分支持 |
| `resolution=merge-duplicates` | 支持 |
| `resolution=ignore-duplicates` | 支持 |
| `missing=default` | 部分支持 |
| `handling=strict` | 支持 |
| `handling=lenient` | 支持 |
## Accept [#accept]
| 值 | 支持情况 |
| --- | --- |
| `application/json` | 支持 |
| `*/*` | 支持 |
| `application/vnd.pgrst.object+json` | 支持 |
| `text/csv` | 不支持 |
| `application/geo+json` | 不支持 |
| `application/vnd.pgrst.plan*` | 不支持 |
## 查询语法 [#查询语法]
| 值 | 支持情况 |
| --- | --- |
| `not` | 支持 |
| `and/or/not.and/not.or` | 支持 |
| `JSON paths (->, ->>)` | 支持 |
| `aliases` | 支持 |
| `link embedding` | 支持 |
| `!field hint` | 支持 |
| `embedded filters/order/pagination` | 不支持 |
| `casts (::)` | 不支持 |
| `aggregates` | 不支持 |
| `spread (...)` | 不支持 |
| `!inner/!left` | 不支持 |
| `operator(any)/operator(all)` | 不支持 |
planned/estimated 当前返回精确计数；字段可以配置 default：批量插入中有的行提供、有的行缺失的列，带 missing=default 时缺失处取字段 default，否则按 PostgREST 写 null；所有行都未提供的列始终取 default（没有 default 时为 null）。cs/cd/ov 接收数组（`{a,b}` 或 `["a"]`）；json 字段上的 cs/cd 还接受 JSON 对象，按 jsonb 包含判断，例如 `meta=cs.{"color":"red"}`（键值逐层包含）；cs 还接受 JSON 标量，数组顶层含该元素即匹配，例如 `meta=cs."a"`。`cs.{}`/`cd.{}` 在 json 字段上是空对象，在数组字段上是空数组。一次 DELETE 删除的行之间互相引用不阻断删除，只要有引用者不在本次删除中就返回 409 23503。like/ilike 只适用于 string 字段与 `->>` 文本路径，用在其他类型返回 400 42883。字符串按二进制序（区分大小写，大写在小写前）比较与排序，不支持按 lower() 排序；需要不区分大小写排序时，另存一个小写字段并按它排序。GET/HEAD 带 If-None-Match 且与当前 ETag 匹配时返回 304、无正文。不支持的 Accept 返回 406 PGRST107。upsert 仅接受 id 或单个 unique 字段。
Prefer 中的未知值默认忽略；handling=strict 时返回 400 PGRST122。单对象 Accept 恰好匹配一行时返回对象，否则返回 406 PGRST116。 其他不支持的 Accept 返回 406 PGRST107。
## 未开放服务 [#未开放服务]
| 路径 | HTTP | code |
| --- | --- | --- |
| /supabase/{database_id}/auth/v1/{+path} | 501 | not_implemented |
| /supabase/{database_id}/storage/v1/{+path} | 501 | not_implemented |
| /supabase/{database_id}/realtime/v1/{+path} | 501 | not_implemented |
| /supabase/{database_id}/functions/v1/{+path} | 501 | not_implemented |
| /supabase/{database_id}/graphql/v1/{+path} | 501 | not_implemented |
这些服务返回 x-should-retry: false。它们的错误体与表端点不同，只有 code 和 message。
[错误码表与错误体](/docs/api/native/database/errors)
# 读写行
[指南 →](/docs/cloud/services/database/quickstart)
`/supabase/{database_id}/rest/v1/{table}`
与同一库的其它入口读写相同的行；错误使用 PostgREST code。
[支持矩阵与初始化](/docs/api/compatible/supabase)
## 参数与请求头 [#参数与请求头]
| 名称 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |
| select | query | 列名列表；支持 *、别名、JSON 路径及 link 关联展开。不支持类型转换、聚合、展开运算和连接修饰。 |
| {column} | query | 把 {column} 换为字段名或 JSON 路径，例如 title=eq.summary；不同列的条件同时生效。 |
| and | query | 括号内的条件全部成立，例如 (done.eq.false,title.neq.draft)。 |
| or | query | 括号内任一条件成立。 |
| not.and | query | 否定全部条件成立。 |
| not.or | query | 否定任一条件成立。 |
| order | query | 逗号分隔的字段，可带 asc/desc、nullsfirst/nullslast；支持 JSON 路径。 |
| limit | query | 最多返回的条数。 |
| offset | query | 跳过的行数。 |
| on_conflict | query | upsert 的冲突键：id 或单个 unique 字段；配合 Prefer 的 resolution。 |
| columns | query | 写入列的逗号分隔列表；列表之外的输入键被忽略。 |
| Range | header | GET/HEAD 的闭区间，例如 0-9；与 limit/offset 取交集。 |
| Range-Unit | header | items；其它单位使 Range 被忽略。 |
| Prefer | header | 逗号分隔的偏好。未知值默认被忽略；handling=strict 时返回 400 PGRST122。 |
| Accept | header | application/json、*/* 或 application/vnd.pgrst.object+json；单对象模式必须恰好匹配一行，否则返回 406 PGRST116。其他媒体类型返回 406 PGRST107；text/csv、application/geo+json 与 application/vnd.pgrst.plan 返回 400 PGRST127。 |
| If-None-Match | header | 上次 GET/HEAD 返回的 ETag（弱比较）；与当前 ETag 匹配时返回 304，无正文。 |
POST 接受单个对象或对象数组；PATCH 接受对象。系统列由服务管理。写入默认不返回正文，使用 Prefer: return=representation（SDK 的 .select()）返回行。PATCH 和 DELETE 只影响匹配过滤器的行；省略过滤器会影响全部匹配行。
| 响应头 | 说明 |
| --- | --- |
| Content-Range | 本次行范围/总数；未请求计数时总数为 *。 |
| Preference-Applied | 已应用的偏好。 |
| ETag | GET/HEAD 返回的版本标记；请求带 If-None-Match 且与之匹配时返回 304、无正文。 |
| Location | POST 使用 return=headers-only 时的新行地址。 |
读取通常为 200；请求计数且只返回部分行时为 206。POST 为 201。PATCH/DELETE 使用 representation 时为 200，否则为 204。HEAD 没有正文。If-None-Match 与当前 ETag 匹配时返回 304。datetime 值统一按 UTC、3 位毫秒保存和读出（如 2026-10-11T00:30:00.000Z），精度为毫秒，超过 3 位的小数秒四舍五入。
## 查询行 [#查询行]
`GET /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error } = await supabase.from("tasks").select("*").order("title").limit(10);
if (error) throw error;
console.log(data);
```
### 响应 [#响应]
#### HTTP 200 [#http-200]
Success; write bodies require Prefer: return=representation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
#### HTTP 206 [#http-206]
Partial range with requested count
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
响应示例 — HTTP 200
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| etag | W/"5.1" |
| range-unit | items |
```json
[
{
"id": "rec_e88fcbd357aa49c9",
"version": 1,
"created_at": "2026-10-11T17:42:00.094Z",
"updated_at": "2026-10-11T17:42:00.094Z",
"title": "Write a summary",
"done": false
}
]
```
## 统计行 [#统计行]
`HEAD /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error, count } = await supabase.from("tasks").select("*", { head: true, count: "exact" });
if (error) throw error;
console.log(count);
```
### 响应 [#响应-1]
#### HTTP 200 [#http-200-1]
Success; write bodies require Prefer: return=representation
未声明响应体。
#### HTTP 206 [#http-206-1]
Partial range with requested count
未声明响应体。
响应示例 — HTTP 200
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/1 |
| preference-applied | count=exact |
| etag | W/"5.1" |
| range-unit | items |
无响应正文。
## 插入行 [#插入行]
`POST /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error } = await supabase.from("tasks").insert({"title":"Write a summary","done":false}).select();
if (error) throw error;
console.log(data);
```
### 响应 [#响应-2]
#### HTTP 201 [#http-201]
Success; write bodies require Prefer: return=representation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
响应示例 — HTTP 201
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |
```json
[
{
"id": "rec_e88fcbd357aa49c9",
"version": 1,
"created_at": "2026-10-11T17:42:00.094Z",
"updated_at": "2026-10-11T17:42:00.094Z",
"title": "Write a summary",
"done": false
}
]
```
## 更新行 [#更新行]
`PATCH /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error } = await supabase.from("tasks").update({ done: true }).eq("title", "Write a summary").select();
if (error) throw error;
console.log(data);
```
### 响应 [#响应-3]
#### HTTP 200 [#http-200-2]
Success; write bodies require Prefer: return=representation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
#### HTTP 204 [#http-204]
Success without a body
未声明响应体。
响应示例 — HTTP 200
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |
```json
[
{
"id": "rec_e88fcbd357aa49c9",
"version": 2,
"created_at": "2026-10-11T17:42:00.094Z",
"updated_at": "2026-10-11T17:42:01.047Z",
"title": "Write a summary",
"done": true
}
]
```
## 合并行 [#合并行]
`POST /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error } = await supabase.from("tasks").upsert({"title":"Write a summary","done":true}, { onConflict: "title" }).select();
if (error) throw error;
console.log(data);
```
### 响应 [#响应-4]
#### HTTP 201 [#http-201-1]
Success; write bodies require Prefer: return=representation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
响应示例 — HTTP 201
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | resolution=merge-duplicates, return=representation |
| range-unit | items |
```json
[
{
"id": "rec_e88fcbd357aa49c9",
"version": 3,
"created_at": "2026-10-11T17:42:00.094Z",
"updated_at": "2026-10-11T17:42:01.735Z",
"title": "Write a summary",
"done": true
}
]
```
## 删除行 [#删除行]
`DELETE /supabase/{database_id}/rest/v1/{table}`
```typescript
const { data, error } = await supabase.from("tasks").delete().eq("title", "Write a summary").select();
if (error) throw error;
console.log(data);
```
### 响应 [#响应-5]
#### HTTP 200 [#http-200-3]
Success; write bodies require Prefer: return=representation
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].version | integer | |
| [].created_at | string | |
| [].updated_at | string | |
**application/vnd.pgrst.object+json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| version | integer | |
| created_at | string | |
| updated_at | string | |
#### HTTP 204 [#http-204-1]
Success without a body
未声明响应体。
响应示例 — HTTP 200
| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |
```json
[
{
"id": "rec_e88fcbd357aa49c9",
"version": 3,
"created_at": "2026-10-11T17:42:00.094Z",
"updated_at": "2026-10-11T17:42:01.735Z",
"title": "Write a summary",
"done": true
}
]
```
# Cloudinary 兼容接口
用官方 Cloudinary SDK 管理一个素材库。只需以下三项配置；API Key 作为 Bearer 凭据发送。
[指南 →](/docs/cloud/services/media/quickstart)
`https://api.deepraxis.ai/cloudinary/v1_1/{library_id}`
| 配置 | 值 |
| --- | --- |
| cloud_name | library_id |
| oauth_token | API Key |
| upload_prefix | https://api.deepraxis.ai/cloudinary |
## Node.js [#nodejs]
```bash
npm install cloudinary@2
```
```javascript
import { v2 as cloudinary } from "cloudinary";
cloudinary.config({
cloud_name: process.env.LIBRARY_ID,
oauth_token: process.env.PRAXIS_API_KEY,
upload_prefix: "https://api.deepraxis.ai/cloudinary",
});
```
## Python [#python]
```bash
python -m pip install cloudinary
```
```python
import os
import cloudinary
import cloudinary.uploader
import cloudinary.api
cloudinary.config(
cloud_name=os.environ["LIBRARY_ID"],
oauth_token=os.environ["PRAXIS_API_KEY"],
upload_prefix="https://api.deepraxis.ai/cloudinary",
)
```
## 支持矩阵 [#支持矩阵]
| 操作 | 支持 |
| --- | --- |
| GET /v1_1/{library_id}/resources/visual_search | 支持 |
| POST /v1_1/{library_id}/resources/visual_search | 支持 |
| POST /v1_1/{library_id}/{resource_type}/upload | 支持 |
| POST /v1_1/{library_id}/{resource_type}/destroy | 支持 |
| POST /v1_1/{library_id}/{resource_type}/rename | 支持 |
| POST /v1_1/{library_id}/{resource_type}/tags | 支持 |
| POST /v1_1/{library_id}/{resource_type}/context | 支持 |
| POST /v1_1/{library_id}/{resource_type}/explicit | 支持 |
| GET /v1_1/{library_id}/resources/search | 支持 |
| POST /v1_1/{library_id}/resources/search | 支持 |
| GET /v1_1/{library_id}/resources | 支持 |
| GET /v1_1/{library_id}/resources/{resource_type} | 支持 |
| GET /v1_1/{library_id}/resources/{resource_type}/upload | 支持 |
| GET /v1_1/{library_id}/resources/{asset_id} | 支持 |
| GET /v1_1/{library_id}/resources/by_asset_ids | 支持 |
| GET /v1_1/{library_id}/resources/by_asset_folder | 支持 |
| GET /v1_1/{library_id}/resources/{resource_type}/tags/{tag} | 支持 |
| GET /v1_1/{library_id}/resources/{resource_type}/context | 支持 |
| GET /v1_1/{library_id}/resources/{resource_type}/upload/{public_id} | 支持 |
| POST /v1_1/{library_id}/resources/by_asset_ids | 支持 |
| POST /v1_1/{library_id}/resources/{resource_type}/upload/{public_id} | 支持 |
| PUT /v1_1/{library_id}/resources/{resource_type}/upload/{public_id} | 支持 |
| DELETE /v1_1/{library_id}/resources/{resource_type}/upload | 支持 |
| DELETE /v1_1/{library_id}/resources/{resource_type}/tags/{tag} | 支持 |
| GET /v1_1/{library_id}/tags/{resource_type} | 支持 |
| GET /v1_1/{library_id}/folders | 支持 |
| GET /v1_1/{library_id}/folders/{folder} | 支持 |
| POST /v1_1/{library_id}/folders/{folder} | 支持 |
| PUT /v1_1/{library_id}/folders/{folder} | 支持 |
| DELETE /v1_1/{library_id}/folders/{folder} | 支持 |
| GET /v1_1/{library_id}/ping | 支持 |
| GET /v1_1/{library_id}/usage | 部分支持 |
| GET /v1_1/{library_id}/usage/{date} | 部分支持 |
usage 只返回当前存储字节数与素材数，日期不选择历史统计。
## 不支持的操作 [#不支持的操作]
| 端点 | HTTP |
| --- | --- |
| upload_presets | 400 |
| metadata_fields | 400 |
| transformations | 400 |
| streaming_profiles | 400 |
| upload_mappings | 400 |
| triggers | 400 |
| derived_resources | 400 |
| relations | 400 |
| restore | 400 |
| backups | 400 |
| text | 400 |
| sprite | 400 |
| multi | 400 |
| explode | 400 |
| generate_archive | 400 |
| create_slideshow | 400 |
| download_backup_asset | 400 |
| folders/search | 400 |
上述端点错误消息含 is not supported；private 与 authenticated 交付类型也返回 400。
## 上传参数 [#上传参数]
| 参数 | 支持 |
| --- | --- |
| file | 支持 |
| public_id | 支持 |
| public_id_prefix | 支持 |
| display_name | 支持 |
| asset_folder | 支持 |
| use_filename | 支持 |
| unique_filename | 支持 |
| use_filename_as_display_name | 支持 |
| filename_override | 支持 |
| overwrite | 支持 |
| tags | 支持 |
| context | 支持 |
| auto_tagging | 部分支持 |
| resource_type | 支持 |
| eager | 不支持 |
| eager_async | 不支持 |
| eager_notification_url | 不支持 |
| async | 不支持 |
| notification_url | 不支持 |
| upload_preset | 不支持 |
| moderation | 不支持 |
| detection | 不支持 |
| ocr | 不支持 |
| raw_convert | 不支持 |
| background_removal | 不支持 |
| categorization | 不支持 |
| transformation | 不支持 |
| responsive_breakpoints | 不支持 |
| proxy | 不支持 |
| backup | 不支持 |
| return_delete_token | 不支持 |
| access_control | 不支持 |
| access_mode | 不支持 |
| metadata | 不支持 |
| face_coordinates | 不支持 |
| custom_coordinates | 不支持 |
| regions | 不支持 |
| quality_analysis | 不支持 |
| accessibility_analysis | 不支持 |
| cinemagraph_analysis | 不支持 |
| media_metadata | 不支持 |
| phash | 不支持 |
| colors | 不支持 |
| faces | 不支持 |
| image_metadata | 不支持 |
| exif | 不支持 |
| invalidate | 不支持 |
| type | 不支持 |
不支持的上传参数返回 400，消息为 Unsupported upload parameter: 参数名。
[错误体与错误码](/docs/api/native/media/errors)
# 上传与管理
官方 SDK 的 `upload("file_…")` 会把字符串当作本地路径。从文件导入请使用自有接口 `POST /media/v1/libraries/{library_id}/assets/import`，见[导入文件](/docs/api/native/media/assets#导入文件)。
[指南 →](/docs/cloud/services/media/quickstart)
上传接受文件字节、HTTPS URL 或 data URI。音频使用 video，自动识别使用 auto。SDK 的 upload\_large 将分片发送到同一 upload 端点。
tags 可写成逗号分隔字符串、数组或多个 tags 字段（-F tags=a -F tags=b），三者等价；逗号分隔时每项去首尾空白并丢弃空项。0 字节文件返回 FILE\_EMPTY；读不出宽高的图片返回 Invalid image file；其他任意文件作为 raw 接受。
```javascript
await new Promise((resolve, reject) => {
cloudinary.uploader.upload_large("./video.mp4", {
resource_type: "video",
chunk_size: 20 * 1024 * 1024,
}, (error, result) => error ? reject(error) : resolve(result));
});
```
每片共享 X-Unique-Upload-Id。Content-Range 为 bytes 起点-终点/总字节数；未知总数用 -1，末片给最终大小。非末片至少 5 MiB 且等长。会话有效期 24 小时。中间片返回 done=false 与 upload\_id；末片返回素材和 done=true。
[指南 →](/docs/cloud/services/media/quickstart)
[基础地址与鉴权](/docs/api/compatible/cloudinary)
## 上传素材 [#上传素材]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/upload`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| X-Unique-Upload-Id | header | string | — |
| Content-Range | header | string | — |
### 请求体 [#请求体]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| file | string / string | 是 | 文件字节、HTTPS URL、data URI 或同账户 file_… |
| public_id | string | 否 | 交付地址中的素材名称，可带路径 |
| public_id_prefix | string | 否 | public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 / |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| use_filename | boolean | 否 | 用文件名生成 public_id |
| unique_filename | boolean | 否 | 自动附加唯一后缀 |
| use_filename_as_display_name | boolean | 否 | 用文件名作为显示名称 |
| filename_override | string | 否 | 覆盖原文件名称 |
| overwrite | boolean | 否 | 是否覆盖同名素材 |
| tags | string / string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | string / object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| auto_tagging | number | 否 | 理解后将达到阈值的标签合并；0–1 |
| resource_type | ResourceType / "auto" | 否 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
返回: `CloudinaryResource`.
### 响应 [#响应]
#### HTTP 200 [#http-200]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
| done | boolean | |
| upload_id | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/upload" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","public_id":"walk-lib-r1-MDP-1791733789929-plain","tags":["docs"]}'
```
HTTP 200
```json
{
"asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
"public_id": "walk-lib-r1-MDP-1791733789929-plain",
"display_name": "walk-lib-r1-MDP-1791733789929-plain",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733810,
"version_id": "fdf3c8cd40c2424d86e8397425a69857",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"created_at": "2026-10-11T15:50:10.842Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"placeholder": false
}
```
## 删除素材 [#删除素材]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/destroy`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
### 请求体 [#请求体-1]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
返回: `DestroyResult`.
### 响应 [#响应-1]
#### HTTP 200 [#http-200-1]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| result | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/destroy" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"public_id":"docs/renamed"}'
```
HTTP 200
```json
{
"result": "ok"
}
```
## 重命名 [#重命名]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/rename`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
### 请求体 [#请求体-2]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| from_public_id | string | 是 | 原 public_id |
| to_public_id | string | 是 | 新 public_id |
| overwrite | boolean | 否 | 是否覆盖同名素材 |
返回: `CloudinaryResource`.
### 响应 [#响应-2]
#### HTTP 200 [#http-200-2]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/rename" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"from_public_id":"docs/pixel","to_public_id":"docs/renamed"}'
```
HTTP 200
```json
{
"asset_id": "9339cdae93804c0c8c65d5189ef1f646",
"public_id": "docs/renamed",
"display_name": "Sample image",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538418,
"version_id": "35848c1529994e338e7aa634a1c13d9c",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"context": {
"custom": {
"alt": "Sample"
}
},
"created_at": "2026-10-09T09:33:38.899Z",
"url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
"placeholder": false
}
```
## 修改标签 [#修改标签]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/tags`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
### 请求体 [#请求体-3]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| public_ids | string[] | 是 | 素材 public_id 列表 |
| tag | string | 否 | 标签名称 |
| command | add / remove / replace / remove_all | 是 | 标签或上下文操作 |
返回: `PublicIds`.
### 响应 [#响应-3]
#### HTTP 200 [#http-200-3]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| public_ids | array<string> | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/tags" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"public_ids":["docs/pixel"],"tag":"sample","command":"add"}'
```
HTTP 200
```json
{
"public_ids": [
"docs/pixel"
]
}
```
## 修改上下文 [#修改上下文]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/context`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
### 请求体 [#请求体-4]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| public_ids | string[] | 是 | 素材 public_id 列表 |
| context | string / object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| command | add / remove_all | 是 | 标签或上下文操作 |
返回: `PublicIds`.
### 响应 [#响应-4]
#### HTTP 200 [#http-200-4]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| public_ids | array<string> | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/context" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"public_ids":["docs/pixel"],"context":"alt=Sample","command":"add"}'
```
HTTP 200
```json
{
"public_ids": [
"docs/pixel"
]
}
```
## 更新素材 [#更新素材]
`POST /cloudinary/v1_1/{library_id}/{resource_type}/explicit`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw / auto | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
### 请求体 [#请求体-5]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| tags | string / string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | string / object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
返回: `CloudinaryResource`.
### 响应 [#响应-5]
#### HTTP 200 [#http-200-5]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/explicit" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"public_id":"docs/pixel","tags":["docs"]}'
```
HTTP 200
```json
{
"asset_id": "9339cdae93804c0c8c65d5189ef1f646",
"public_id": "docs/pixel",
"display_name": "Sample image",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538418,
"version_id": "35848c1529994e338e7aa634a1c13d9c",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"context": {
"custom": {
"alt": "Sample"
}
},
"created_at": "2026-10-09T09:33:38.899Z",
"url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
"placeholder": false
}
```
## CloudinaryResource [#cloudinaryresource]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |
## DestroyResult [#destroyresult]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| result | ok / not found | 是 | 操作结果 |
## PublicIds [#publicids]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| public_ids | string[] | 是 | 素材 public_id 列表 |
## ChunkPending [#chunkpending]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| done | false | 是 | 已完成数量；分片响应中表示是否完成 |
| upload_id | string | 是 | 分片会话标识 |
## ChunkComplete [#chunkcomplete]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| done | true | 是 | 已完成数量；分片响应中表示是否完成 |
# 资源管理
Admin 管理当前库的素材。usage 只返回当前存储量和素材数。
[指南 →](/docs/cloud/services/media/quickstart)
[基础地址与鉴权](/docs/api/compatible/cloudinary)
## 读取素材 [#读取素材]
`GET /cloudinary/v1_1/{library_id}/resources`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应]
#### HTTP 200 [#http-200]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "9dfa312ef9bc4b00816339b598b1152c",
"public_id": "walk-lib-r1-MDP-1791733789929-tagged",
"display_name": "walk-lib-r1-MDP-1791733789929-tagged",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733815,
"version_id": "26cb8171caa5431b8373ad417fd71e32",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"processing": {
"state": "processing",
"kinds": {
"embedding": "running",
"visual": "failed",
"tagging": "failed"
},
"updated_at": "2026-10-11T15:50:21.512Z"
},
"created_at": "2026-10-11T15:50:15.996Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"placeholder": false
},
{
"asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
"public_id": "walk-lib-r1-MDP-1791733789929-plain",
"display_name": "walk-lib-r1-MDP-1791733789929-plain",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733810,
"version_id": "fdf3c8cd40c2424d86e8397425a69857",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-11T15:50:10.842Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-1]
`GET /cloudinary/v1_1/{library_id}/resources/{resource_type}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-1]
#### HTTP 200 [#http-200-1]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-2]
`GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-2]
#### HTTP 200 [#http-200-2]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-3]
`GET /cloudinary/v1_1/{library_id}/resources/{asset_id}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_id | path | string | 素材 ID |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `CloudinaryResource`.
### 响应 [#响应-3]
#### HTTP 200 [#http-200-3]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/9dfa312ef9bc4b00816339b598b1152c" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"asset_id": "9dfa312ef9bc4b00816339b598b1152c",
"public_id": "walk-lib-r1-MDP-1791733789929-tagged",
"display_name": "walk-lib-r1-MDP-1791733789929-tagged",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733815,
"version_id": "26cb8171caa5431b8373ad417fd71e32",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"processing": {
"state": "processing",
"kinds": {
"embedding": "running",
"visual": "failed",
"tagging": "failed"
},
"updated_at": "2026-10-11T15:50:21.512Z"
},
"created_at": "2026-10-11T15:50:15.996Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"placeholder": false
}
```
## 读取素材 [#读取素材-4]
`GET /cloudinary/v1_1/{library_id}/resources/by_asset_ids`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-4]
#### HTTP 200 [#http-200-4]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_ids?asset_ids[]=e5f3de0d8609482d8b351894b133c8cb" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-5]
`GET /cloudinary/v1_1/{library_id}/resources/by_asset_folder`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-5]
#### HTTP 200 [#http-200-5]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_folder?asset_folder=examples" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-6]
`GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/tags/{tag}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| tag | path | string | 标签名称 |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-6]
#### HTTP 200 [#http-200-6]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/tags/docs" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-7]
`GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/context`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-7]
#### HTTP 200 [#http-200-7]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/context?key=alt&value=sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 读取素材 [#读取素材-8]
`GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload/{public_id}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| public_id | path | string | 交付地址中的素材名称，可带路径 |
| prefix | query | string | — |
| public_ids | query | string[] | 素材 public_id 列表 |
| asset_ids | query | string[] | — |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| key | query | string | — |
| value | query | string | — |
| tags | query | string | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | query | string | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| direction | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `CloudinaryResource`.
### 响应 [#响应-8]
#### HTTP 200 [#http-200-8]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload/examples/pixel" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"context": {
"custom": {
"alt": "sample"
}
},
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
```
## 按 ID 读取 [#按-id-读取]
`POST /cloudinary/v1_1/{library_id}/resources/by_asset_ids`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
### 请求体 [#请求体]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_ids | string[] | 是 | — |
| max_results | integer | 否 | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
返回: `ResourcePage`.
### 响应 [#响应-9]
#### HTTP 200 [#http-200-9]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| next_cursor | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_ids" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"asset_ids":["e5f3de0d8609482d8b351894b133c8cb"]}'
```
HTTP 200
```json
{
"resources": [
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "pixel",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
]
}
```
## 更新素材 [#更新素材]
`POST /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload/{public_id}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| public_id | path | string | 交付地址中的素材名称，可带路径 |
### 请求体 [#请求体-1]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| tags | string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
返回: `CloudinaryResource`.
### 响应 [#响应-10]
#### HTTP 200 [#http-200-10]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload/examples/pixel" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"display_name":"Sample image"}'
```
HTTP 200
```json
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "Sample image",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"context": {
"custom": {
"alt": "sample"
}
},
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
```
## 更新素材 [#更新素材-1]
`PUT /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload/{public_id}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| public_id | path | string | 交付地址中的素材名称，可带路径 |
### 请求体 [#请求体-2]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| tags | string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
返回: `CloudinaryResource`.
### 响应 [#响应-11]
#### HTTP 200 [#http-200-11]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | |
| public_id | string | |
| display_name | string | |
| asset_folder | string | |
| resource_type | string | |
| type | string | |
| format | string | |
| version | number | |
| version_id | string | |
| bytes | number | |
| etag | string | |
| width | number | |
| height | number | |
| duration | number | |
| pages | number | |
| is_audio | boolean | |
| original_filename | string | |
| tags | array<string> | |
| context | object | |
| context.custom | object | |
| created_at | string | |
| url | string | |
| secure_url | string | |
| placeholder | boolean | |
| existing | boolean | |
| processing | object | |
| processing.state | string | |
| processing.kinds | object | |
| processing.updated_at | string | |
```bash
curl -X PUT "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload/examples/pixel" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"tags":["docs"]}'
```
HTTP 200
```json
{
"asset_id": "e5f3de0d8609482d8b351894b133c8cb",
"public_id": "examples/pixel",
"display_name": "Sample image",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538435,
"version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"tags": [
"docs"
],
"context": {
"custom": {
"alt": "sample"
}
},
"created_at": "2026-10-09T09:33:55.536Z",
"url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
"placeholder": false
}
```
## 删除素材 [#删除素材]
`DELETE /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| public_ids | query | string[] | 素材 public_id 列表 |
| prefix | query | string | — |
| all | query | boolean | — |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `DeletedResources`.
### 响应 [#响应-12]
#### HTTP 200 [#http-200-12]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| deleted | object | |
| partial | boolean | |
| next_cursor | string | |
```bash
curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"prefix":"imported/"}'
```
HTTP 200
```json
{
"deleted": {},
"partial": false
}
```
## 删除素材 [#删除素材-1]
`DELETE /cloudinary/v1_1/{library_id}/resources/{resource_type}/tags/{tag}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| tag | path | string | 标签名称 |
| public_ids | query | string[] | 素材 public_id 列表 |
| prefix | query | string | — |
| all | query | boolean | — |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `DeletedResources`.
### 响应 [#响应-13]
#### HTTP 200 [#http-200-13]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| deleted | object | |
| partial | boolean | |
| next_cursor | string | |
```bash
curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/tags/remove-me" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
```
HTTP 200
```json
{
"deleted": {
"tagged/pixel": "deleted"
},
"partial": false
}
```
## 列出标签 [#列出标签]
`GET /cloudinary/v1_1/{library_id}/tags/{resource_type}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| resource_type | path | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| prefix | query | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `Tags`.
### 响应 [#响应-14]
#### HTTP 200 [#http-200-14]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| tags | array<string> | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/tags/image" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"tags": [
"docs"
]
}
```
## 列出文件夹 [#列出文件夹]
`GET /cloudinary/v1_1/{library_id}/folders`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `CompatFolders`.
### 响应 [#响应-15]
#### HTTP 200 [#http-200-15]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| folders | array<object> | |
| folders[].name | string | |
| folders[].path | string | |
| total_count | number | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"folders": [
{
"name": "examples",
"path": "examples"
}
],
"total_count": 1
}
```
## 列出文件夹 [#列出文件夹-1]
`GET /cloudinary/v1_1/{library_id}/folders/{folder}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| folder | path | string | — |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
返回: `CompatFolders`.
### 响应 [#响应-16]
#### HTTP 200 [#http-200-16]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| folders | array<object> | |
| folders[].name | string | |
| folders[].path | string | |
| total_count | number | |
| next_cursor | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders/examples" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"folders": [],
"total_count": 0
}
```
## 创建文件夹 [#创建文件夹]
`POST /cloudinary/v1_1/{library_id}/folders/{folder}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| folder | path | string | — |
返回: `FolderResult`.
### 响应 [#响应-17]
#### HTTP 200 [#http-200-17]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
```
HTTP 200
```json
{
"success": true,
"path": "sample"
}
```
## 重命名文件夹 [#重命名文件夹]
`PUT /cloudinary/v1_1/{library_id}/folders/{folder}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| folder | path | string | — |
### 请求体 [#请求体-3]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| to_folder | string | 是 | 目标文件夹路径 |
返回: `FolderResult`.
### 响应 [#响应-18]
#### HTTP 200 [#http-200-18]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
## 删除文件夹 [#删除文件夹]
`DELETE /cloudinary/v1_1/{library_id}/folders/{folder}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| folder | path | string | — |
返回: `FolderResult`.
### 响应 [#响应-19]
#### HTTP 200 [#http-200-19]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object | |
```bash
curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
```
HTTP 200
```json
{
"success": true,
"path": "sample"
}
```
## 检查连接 [#检查连接]
`GET /cloudinary/v1_1/{library_id}/ping`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
返回: `Ping`.
### 响应 [#响应-20]
#### HTTP 200 [#http-200-20]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| status | string | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/ping" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"status": "ok"
}
```
## 读取用量 [#读取用量]
`GET /cloudinary/v1_1/{library_id}/usage`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
返回: `Usage`.
### 响应 [#响应-21]
#### HTTP 200 [#http-200-21]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| storage | object | |
| storage.usage | number | |
| objects | object | |
| objects.usage | number | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/usage" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"storage": {
"usage": 70
},
"objects": {
"usage": 1
}
}
```
## 读取用量 [#读取用量-1]
`GET /cloudinary/v1_1/{library_id}/usage/{date}`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| date | path | string | — |
返回: `Usage`.
### 响应 [#响应-22]
#### HTTP 200 [#http-200-22]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| storage | object | |
| storage.usage | number | |
| objects | object | |
| objects.usage | number | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/usage/2026-10-09" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"storage": {
"usage": 70
},
"objects": {
"usage": 1
}
}
```
## ResourcePage [#resourcepage]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| resources | SearchResource[] | 是 | 本页素材 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
## CloudinaryResource [#cloudinaryresource]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |
## DeletedResources [#deletedresources]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| deleted | object | 是 | 删除结果 |
| partial | boolean | 是 | 是否还有未处理的后续页 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
## Tags [#tags]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
## CompatFolders [#compatfolders]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| folders | object[] | 是 | 文件夹列表 |
| total_count | number | 是 | 匹配总数 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
## FolderResult [#folderresult]
| 字段 | 类型 | 必填 | 说明 |
| -- | -- | -- | -- |
## Ping [#ping]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| status | "ok" | 是 | 资源状态 |
## Usage [#usage]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| storage | object | 是 | 存储字节用量 |
| objects | object | 是 | 素材数量 |
# 检索
[指南 →](/docs/cloud/services/media/quickstart)
表达式检索仅支持以下子集。不支持的语法或字段返回 HTTP 400 INVALID\_EXPRESSION；兼容错误体只包含消息。默认省略 tags 与 context；需要时用 with\_field 请求。
| 语法 | 含义 |
| --- | --- |
| AND / OR / NOT / - / ( ) | 布尔组合；相邻条件默认 AND |
| field:value / field=value | 字段匹配 |
| bytes > 1000 / width >= 160 | 数值比较；也支持 height、duration |
| created_at >= 2026-01-01 / uploaded_at > 7d | 日期或相对时间，支持 d/w/m/y |
| tags:docs / context.alt:"sample image" | 标签和自定义文字 |
| public_id:docs* | 仅末尾通配符 |
| "sample image" | 短语 |
| sunset | 裸词：在 public_id、display_name、tags、context 以及理解得到的描述、图片文字、转写中做全文匹配，不区分大小写 |
| ~ / ^ / [a TO z] / *prefix / a*b | 不支持，返回 400 |
字段名不区分大小写（RESOURCE\_TYPE:image 等同 resource\_type:image）；resource\_type、type、format 的值不区分大小写；tags、context 等其他字段的值区分大小写。空表达式返回全部素材；无法解析的表达式返回 400 INVALID\_EXPRESSION。
查询字段: `asset_id, resource_type, type, format, public_id, asset_folder, display_name, tags, bytes, width, height, duration, created_at, uploaded_at, context.`.
排序字段: `created_at, public_id, display_name, bytes, uploaded_at`.
统计字段: `resource_type, format, asset_folder, processing_state`.
[指南 →](/docs/cloud/services/media/quickstart)
[基础地址与鉴权](/docs/api/compatible/cloudinary)
## 以图搜图 [#以图搜图]
`GET /cloudinary/v1_1/{library_id}/resources/visual_search`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| image_asset_id | query | string | 本库素材 ID |
| image_url | query | string | 仅接受本库交付 URL，不支持抓取外部 URL |
| text | query | string | 自然语言查询，使用语义检索 |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| filter | query | string | 表达式筛选条件 |
返回: `VisualResources`.
库的 `search.image` 为 true 时可用；不支持的库返回 LIBRARY\_INVALID\_STATE。图片仅接受 JPEG、PNG、WebP、GIF，解码后最大 10 MiB。每个素材返回最高分命中，视频定位到最佳帧。qwen3-vl-embedding 的图片相似度门槛为 0.35。标定来自 2026-10-10 的测试：同图变体 0.82–0.96，同类场景 0.38–0.66，无关图片最高 0.34。
`image_asset_id`、`image_file`（multipart）、`image_url`、`text` 必须且只能传一个。text 使用纯语义检索；返回 `{ "resources": [...] }`。image\_url 只接受本库交付 URL，不抓取外部 URL；外部 URL 返回 400「不支持抓取外部 URL」。
### 响应 [#响应]
#### HTTP 200 [#http-200]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
## 以图搜图 [#以图搜图-1]
`POST /cloudinary/v1_1/{library_id}/resources/visual_search`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
### 请求体 [#请求体]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| image_asset_id | string | 否 | 本库素材 ID |
| image_url | string | 否 | 仅接受本库交付 URL，不支持抓取外部 URL |
| image_file | string | 否 | JPEG、PNG、WebP 或 GIF 文件，最大 10 MiB |
| text | string | 否 | 自然语言查询，使用语义检索 |
| max_results | integer | 否 | 最多 500；检索默认 100，Admin 默认 10 |
| filter | string | 否 | 表达式筛选条件 |
返回: `VisualResources`.
库的 `search.image` 为 true 时可用；不支持的库返回 LIBRARY\_INVALID\_STATE。图片仅接受 JPEG、PNG、WebP、GIF，解码后最大 10 MiB。每个素材返回最高分命中，视频定位到最佳帧。qwen3-vl-embedding 的图片相似度门槛为 0.35。标定来自 2026-10-10 的测试：同图变体 0.82–0.96，同类场景 0.38–0.66，无关图片最高 0.34。
`image_asset_id`、`image_file`（multipart）、`image_url`、`text` 必须且只能传一个。text 使用纯语义检索；返回 `{ "resources": [...] }`。image\_url 只接受本库交付 URL，不抓取外部 URL；外部 URL 返回 400「不支持抓取外部 URL」。
### 响应 [#响应-1]
#### HTTP 200 [#http-200-1]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
## 表达式检索 [#表达式检索]
`GET /cloudinary/v1_1/{library_id}/resources/search`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| expression | query | string | 结构化查询表达式；空表达式返回全部素材 |
| sort_by | query | string | 排序字段与方向 |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | query | string | 下一页游标；没有时为 null 或省略 |
| with_field | query | string[] | 额外返回 tags 或 context |
| aggregate | query | string[] | 统计字段 |
返回: `CompatExpressionSearchResult`.
### 响应 [#响应-2]
#### HTTP 200 [#http-200-2]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total_count | number | |
| time | number | |
| next_cursor | string | |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| aggregations | object | |
```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search?expression=tags%3Adocs" \
-H "Authorization: Bearer $PRAXIS_API_KEY"
```
HTTP 200
```json
{
"total_count": 1,
"time": 0,
"resources": [
{
"asset_id": "9339cdae93804c0c8c65d5189ef1f646",
"public_id": "docs/pixel",
"display_name": "Sample image",
"asset_folder": "examples",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791538418,
"version_id": "35848c1529994e338e7aa634a1c13d9c",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-09T09:33:38.899Z",
"url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
"placeholder": false
}
]
}
```
## 表达式检索 [#表达式检索-1]
`POST /cloudinary/v1_1/{library_id}/resources/search`
| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
### 请求体 [#请求体-1]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| expression | string | 否 | 结构化查询表达式；空表达式返回全部素材 |
| sort_by | object[] | 否 | 排序字段与方向 |
| max_results | integer | 否 | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
| with_field | "tags" / "context"[] | 否 | 额外返回 tags 或 context |
| aggregate | AggregateField[] | 否 | 统计字段 |
返回: `CompatExpressionSearchResult`.
### 响应 [#响应-3]
#### HTTP 200 [#http-200-3]
Successful response.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total_count | number | |
| time | number | |
| next_cursor | string | |
| resources | array<object> | |
| resources[].asset_id | string | |
| resources[].public_id | string | |
| resources[].display_name | string | |
| resources[].asset_folder | string | |
| resources[].resource_type | string | |
| resources[].type | string | |
| resources[].format | string | |
| resources[].version | number | |
| resources[].version_id | string | |
| resources[].bytes | number | |
| resources[].etag | string | |
| resources[].width | number | |
| resources[].height | number | |
| resources[].duration | number | |
| resources[].pages | number | |
| resources[].is_audio | boolean | |
| resources[].original_filename | string | |
| resources[].tags | array<string> | |
| resources[].context | object | |
| resources[].created_at | string | |
| resources[].url | string | |
| resources[].secure_url | string | |
| resources[].placeholder | boolean | |
| resources[].existing | boolean | |
| resources[].processing | object | |
| aggregations | object | |
```bash
curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"expression":"tags:docs"}'
```
HTTP 200
```json
{
"total_count": 2,
"time": 0,
"resources": [
{
"asset_id": "9dfa312ef9bc4b00816339b598b1152c",
"public_id": "walk-lib-r1-MDP-1791733789929-tagged",
"display_name": "walk-lib-r1-MDP-1791733789929-tagged",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733815,
"version_id": "26cb8171caa5431b8373ad417fd71e32",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"processing": {
"state": "processing",
"kinds": {
"embedding": "running",
"visual": "failed",
"tagging": "failed"
},
"updated_at": "2026-10-11T15:50:21.512Z"
},
"created_at": "2026-10-11T15:50:15.996Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"placeholder": false
},
{
"asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
"public_id": "walk-lib-r1-MDP-1791733789929-plain",
"display_name": "walk-lib-r1-MDP-1791733789929-plain",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733810,
"version_id": "fdf3c8cd40c2424d86e8397425a69857",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-11T15:50:10.842Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"placeholder": false
}
]
}
```
## VisualResources [#visualresources]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| resources | CloudinaryResource[] | 是 | 本页素材 |
## CompatExpressionSearchResult [#compatexpressionsearchresult]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| total_count | number | 是 | 匹配总数 |
| time | number | 是 | 检索耗时，整数毫秒，由服务端测得 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
| resources | SearchResource[] | 是 | 本页素材 |
| aggregations | object | 否 | 按请求字段统计 |
## SearchResource [#searchresource]
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |
# 交付与变换
[指南 →](/docs/cloud/services/media/quickstart)
用上传响应的 secure\_url 读取原文件，在 upload 与版本之间插入变换。
`https://media-develop.praxisusercontent.com/{library_id}/{resource_type}/upload/{transformation}/v{version}/{public_id}.{format}`
原文件省略 transformation 及其后斜杠。仅接受以下白名单；其它变换返回错误。
| 参数 | 允许值 |
| --- | --- |
| w_ | 160, 320, 640, 1280 |
| c_ | fill, fit, limit, scale, pad |
| g_ | auto, center |
| f_ | auto, jpg, png, webp, avif |
| q_ | auto, auto:good, auto:eco |
| dpr_ | 1, 2 |
| so_ | 视频秒数，扩展名 .jpg；源文件不超过 100 MiB |
```text
w_160,c_fit
w_320,c_fill,g_center,f_webp,q_auto,dpr_2
```
## 用户内容安全 [#用户内容安全]
交付使用独立的可注册域 `praxisusercontent.com`，与 API 和登录域隔离：Develop 为 `media-develop.praxisusercontent.com`，生产为 `media.praxisusercontent.com`。URL 路径形状不变，交付不携带任何 cookie。
* 只允许 GET 和 HEAD；其他方法返回 405。
* 不向上游转发 cookie 和凭据，响应移除 Set-Cookie。
* 所有响应都带 `X-Content-Type-Options: nosniff`。
* HTML、SVG、XML、JavaScript 类内容都带 `Content-Security-Policy: sandbox` 和 `Content-Disposition: attachment`。
* 支持 Range 请求，部分内容返回 206。
# Browserbase
[连接与使用指南](/docs/cloud/services/browser)
基础地址: `https://api-develop.deepraxis.ai/browserbase`
请求头: `X-BB-API-Key: $PRAXIS_API_KEY`
请求 ID 响应头: `X-Request-Id`
官方 SDK 设置 baseURL 后使用以下接口。代理、反检测、扩展和 Selenium 不可用；region 与 solveCaptchas 接受但忽略。删除登录态返回 200 和 deleted=true；会话响应还可能包含 currentUrl、clients、handoff。
| 操作 | 方法与路径 |
| ---------------------------------------------------------------- | --------------------------------------------- |
| [创建浏览器会话](/docs/api/compatible/browserbase/Sessions_create) | `POST /browserbase/v1/sessions` |
| [列出浏览器会话](/docs/api/compatible/browserbase/Sessions_list) | `GET /browserbase/v1/sessions` |
| [读取浏览器会话](/docs/api/compatible/browserbase/Sessions_get) | `GET /browserbase/v1/sessions/{id}` |
| [关闭浏览器会话](/docs/api/compatible/browserbase/Sessions_update) | `POST /browserbase/v1/sessions/{id}` |
| [读取调试地址](/docs/api/compatible/browserbase/Sessions_getDebug) | `GET /browserbase/v1/sessions/{id}/debug` |
| [读取会话日志](/docs/api/compatible/browserbase/Sessions_getLogs) | `GET /browserbase/v1/sessions/{id}/logs` |
| [读取会话录像](/docs/api/compatible/browserbase/Sessions_getRecording) | `GET /browserbase/v1/sessions/{id}/recording` |
| [创建登录态](/docs/api/compatible/browserbase/Contexts_create) | `POST /browserbase/v1/contexts` |
| [读取登录态](/docs/api/compatible/browserbase/Contexts_get) | `GET /browserbase/v1/contexts/{id}` |
| [删除登录态](/docs/api/compatible/browserbase/Contexts_delete) | `DELETE /browserbase/v1/contexts/{id}` |
# 创建浏览器会话
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 201 [#http-201]
The request has succeeded and a new resource has been created as a result.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| createdAt | string | |
| updatedAt | string | |
| projectId | string | The Project ID linked to the Session. |
| startedAt | string | |
| endedAt | string | |
| expiresAt | string | |
| status | string | |
| proxyBytes | integer | Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips) |
| keepAlive | boolean | Indicates if the Session was created to be kept alive upon disconnections |
| contextId | string | Optional. The Context linked to the Session. |
| region | string | The region where the Session is running. |
| userMetadata | object | Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). |
| connectUrl | string | WebSocket URL to connect to the Session. |
| seleniumRemoteUrl | string | HTTP URL to connect to the Session. |
| signingKey | string | Signing key to use when connecting to the Session via HTTP. |
# 列出浏览器会话
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].createdAt | string | |
| [].updatedAt | string | |
| [].projectId | string | The Project ID linked to the Session. |
| [].startedAt | string | |
| [].endedAt | string | |
| [].expiresAt | string | |
| [].status | string | |
| [].proxyBytes | integer | Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips) |
| [].keepAlive | boolean | Indicates if the Session was created to be kept alive upon disconnections |
| [].contextId | string | Optional. The Context linked to the Session. |
| [].region | string | The region where the Session is running. |
| [].userMetadata | object | Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). |
# 读取浏览器会话
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| createdAt | string | |
| updatedAt | string | |
| projectId | string | The Project ID linked to the Session. |
| startedAt | string | |
| endedAt | string | |
| expiresAt | string | |
| status | string | |
| proxyBytes | integer | Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips) |
| keepAlive | boolean | Indicates if the Session was created to be kept alive upon disconnections |
| contextId | string | Optional. The Context linked to the Session. |
| region | string | The region where the Session is running. |
| userMetadata | object | Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). |
| connectUrl | string | WebSocket URL to connect to the Session. |
| seleniumRemoteUrl | string | HTTP URL to connect to the Session. |
| signingKey | string | Signing key to use when connecting to the Session via HTTP. |
# 关闭浏览器会话
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| createdAt | string | |
| updatedAt | string | |
| projectId | string | The Project ID linked to the Session. |
| startedAt | string | |
| endedAt | string | |
| expiresAt | string | |
| status | string | |
| proxyBytes | integer | Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips) |
| keepAlive | boolean | Indicates if the Session was created to be kept alive upon disconnections |
| contextId | string | Optional. The Context linked to the Session. |
| region | string | The region where the Session is running. |
| userMetadata | object | Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata). |
# 读取调试地址
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| debuggerFullscreenUrl | string | |
| debuggerUrl | string | |
| pages | array<object> | |
| pages[].id | string | |
| pages[].url | string | |
| pages[].faviconUrl | string | |
| pages[].title | string | |
| pages[].debuggerUrl | string | |
| pages[].debuggerFullscreenUrl | string | |
| wsUrl | string | |
# 读取会话日志
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].method | string | |
| [].pageId | integer | |
| [].sessionId | string | |
| [].request | object | |
| [].request.timestamp | integer | milliseconds that have elapsed since the UNIX epoch |
| [].request.params | object | |
| [].request.rawBody | string | |
| [].response | object | |
| [].response.timestamp | integer | milliseconds that have elapsed since the UNIX epoch |
| [].response.result | object | |
| [].response.rawBody | string | |
| [].timestamp | integer | milliseconds that have elapsed since the UNIX epoch |
| [].frameId | string | |
| [].loaderId | string | |
# 读取会话录像
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | |
| [].data | object | See [rrweb documentation](https://github.com/rrweb-io/rrweb/blob/master/docs/recipes/dive-into-event.md). |
| [].sessionId | string | |
| [].timestamp | integer | milliseconds that have elapsed since the UNIX epoch |
| [].type | integer | |
# 创建登录态
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 201 [#http-201]
The request has succeeded and a new resource has been created as a result.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| publicKey | string | The public key to encrypt the user-data-directory. |
| cipherAlgorithm | string | The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm. |
| initializationVectorSize | integer | The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts). |
# 读取登录态
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
## 响应 [#响应]
### HTTP 200 [#http-200]
The request has succeeded.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | |
| createdAt | string | |
| updatedAt | string | |
| projectId | string | The Project ID linked to the uploaded Context. |
| name | string | Optional user-defined name for the Context. Leading and trailing whitespace is trimmed before storage. Names are unique within the project among active Contexts, compared case-insensitively. |
# 删除登录态
[连接与使用指南](/docs/cloud/services/browser)
代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。
此接口返回 200 和 JSON 确认；Browserbase 官方为 204。
## 响应 [#响应]
### HTTP 200 [#http-200]
Context deleted. Praxis returns JSON instead of Browserbase's 204.
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| deleted | boolean | |
# Cloudflare API
（待译）
Cloudflare Workers-compatible face of Application: the official cloudflare SDK paths for Workers, versions, deployments and static assets. Concepts, differences and limits are described under the Application tag.
## 基础地址 [#基础地址]
## 鉴权 [#鉴权]
Authorization: Bearer \
## 端点 [#端点]
* [列出 Worker](/docs/api/compatible/cloudflare/listWorkers) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/workers`
* [创建 Worker](/docs/api/compatible/cloudflare/createWorker) — `POST /cloudflare/client/v4/accounts/{account_id}/workers/workers`
* [获取 Worker](/docs/api/compatible/cloudflare/getWorker) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
* [更新 Worker](/docs/api/compatible/cloudflare/updateWorker) — `PUT /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
* [编辑 Worker](/docs/api/compatible/cloudflare/editWorker) — `PATCH /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
* [删除 Worker](/docs/api/compatible/cloudflare/deleteWorker) — `DELETE /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
* [列出版本](/docs/api/compatible/cloudflare/listVersions) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions`
* [创建版本](/docs/api/compatible/cloudflare/createVersion) — `POST /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions`
* [获取版本](/docs/api/compatible/cloudflare/getVersion) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions/{version_id}`
* [列出部署](/docs/api/compatible/cloudflare/listDeployments) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/scripts/{script_name}/deployments`
* [创建部署](/docs/api/compatible/cloudflare/createDeployment) — `POST /cloudflare/client/v4/accounts/{account_id}/workers/scripts/{script_name}/deployments`
* [获取部署](/docs/api/compatible/cloudflare/getDeployment) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/scripts/{script_name}/deployments/{deployment_id}`
* [获取账号子域](/docs/api/compatible/cloudflare/getSubdomain) — `GET /cloudflare/client/v4/accounts/{account_id}/workers/subdomain`
* [修改账号子域](/docs/api/compatible/cloudflare/putSubdomain) — `PUT /cloudflare/client/v4/accounts/{account_id}/workers/subdomain`
* [创建静态资源上传会话](/docs/api/compatible/cloudflare/createAssetUploadSession) — `POST /cloudflare/client/v4/accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session`
* [上传静态资源](/docs/api/compatible/cloudflare/uploadAssets) — `POST /cloudflare/client/v4/accounts/{account_id}/workers/assets/upload`
* [旧版脚本上传（未支持）](/docs/api/compatible/cloudflare/uploadScriptLegacy) — `PUT /cloudflare/client/v4/accounts/{account_id}/workers/scripts/{script_name}`
#
`GET /cloudflare/client/v4/accounts/{account_id}/workers/workers`
List Workers. order and order\_by are accepted and ignored.
**支持状态: partial**
List Workers. order and order\_by are accepted and ignored.
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ----- | ------- | ----- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| page | query | integer | false | Page number, from 1. |
| per\_page | query | integer | false | Items per page (default 20). |
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | array<object> | Workers. |
| result[].id | string | Worker ID, prefixed wkr_. |
| result[].name | string | Unique per account; lowercase letters, digits and single hyphens. |
| result[].subdomain | object | Public address of the Worker. |
| result[].tags | array<string> | Up to 8 tags. |
| result[].observability | object | Observability settings. |
| result[].logpush | boolean | Always false: unlike Cloudflare, Logpush is not offered. |
| result[].created_on | string | When the Worker was created. |
| result[].updated_on | string | When the Worker last changed. |
| result[].deployed_on | string | null | When the current deployment became active; null before the first deployment. |
| result[].praxis | object | Platform fields: lifecycle status, labels, and soft-delete timestamps. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
# 创建 Worker
`POST /cloudflare/client/v4/accounts/{account_id}/workers/workers`
Create a Worker.
**支持状态: supported**
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ---- | ------ | ---- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
## 请求体 (application/json) [#请求体-applicationjson]
必填: true
| 名称 | 类型 | 说明 |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved. |
| tags | array\ | Up to 8 tags. |
| observability | object | Observability settings. |
| observability.enabled | boolean | Collect logs. |
| subdomain | object | Subdomain settings. |
| subdomain.enabled | boolean | Serve the Worker on its public subdomain (default true). |
| praxis | object | Praxis settings. |
| praxis.labels | object | Up to 16 labels. |
```json
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved.",
"pattern": "^(?!(?:www|api|admin|app|canary|canary-probe|status|docs|console)$)(?!.*--)[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$",
"example": "my-app"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 8,
"description": "Up to 8 tags."
},
"observability": {
"type": "object",
"description": "Observability settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Collect logs."
}
}
},
"subdomain": {
"type": "object",
"description": "Subdomain settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Serve the Worker on its public subdomain (default true)."
}
}
},
"praxis": {
"type": "object",
"description": "Praxis settings.",
"required": [],
"properties": {
"labels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Up to 16 labels."
}
}
}
}
}
```
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | object | |
| result.id | string | Worker ID, prefixed wkr_. |
| result.name | string | Unique per account; lowercase letters, digits and single hyphens. |
| result.subdomain | object | Public address of the Worker. |
| result.tags | array<string> | Up to 8 tags. |
| result.observability | object | Observability settings. |
| result.logpush | boolean | Always false: unlike Cloudflare, Logpush is not offered. |
| result.created_on | string | When the Worker was created. |
| result.updated_on | string | When the Worker last changed. |
| result.deployed_on | string | null | When the current deployment became active; null before the first deployment. |
| result.praxis | object | Platform fields: lifecycle status, labels, and soft-delete timestamps. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
# 获取 Worker
`GET /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
Get a Worker by ID or name.
**支持状态: supported**
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ---- | ------ | ---- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | object | |
| result.id | string | Worker ID, prefixed wkr_. |
| result.name | string | Unique per account; lowercase letters, digits and single hyphens. |
| result.subdomain | object | Public address of the Worker. |
| result.tags | array<string> | Up to 8 tags. |
| result.observability | object | Observability settings. |
| result.logpush | boolean | Always false: unlike Cloudflare, Logpush is not offered. |
| result.created_on | string | When the Worker was created. |
| result.updated_on | string | When the Worker last changed. |
| result.deployed_on | string | null | When the current deployment became active; null before the first deployment. |
| result.praxis | object | Platform fields: lifecycle status, labels, and soft-delete timestamps. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
#
`PUT /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
Update a Worker. Omitted fields stay unchanged (same as PATCH).
**支持状态: partial**
Update a Worker. Omitted fields stay unchanged (same as PATCH).
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ---- | ------ | ---- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
## 请求体 (application/json) [#请求体-applicationjson]
必填: true
| 名称 | 类型 | 说明 |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved. |
| tags | array\ | Replaces the tags. |
| observability | object | Observability settings. |
| observability.enabled | boolean | Collect logs. |
| subdomain | object | Subdomain settings. |
| subdomain.enabled | boolean | Serve the Worker on its public subdomain. |
| praxis | object | Praxis settings. |
| praxis.labels | object | Replaces the labels. |
```json
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string",
"description": "Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved.",
"pattern": "^(?!(?:www|api|admin|app|canary|canary-probe|status|docs|console)$)(?!.*--)[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$",
"example": "my-app"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 8,
"description": "Replaces the tags."
},
"observability": {
"type": "object",
"description": "Observability settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Collect logs."
}
}
},
"subdomain": {
"type": "object",
"description": "Subdomain settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Serve the Worker on its public subdomain."
}
}
},
"praxis": {
"type": "object",
"description": "Praxis settings.",
"required": [],
"properties": {
"labels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Replaces the labels."
}
}
}
}
}
```
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | object | |
| result.id | string | Worker ID, prefixed wkr_. |
| result.name | string | Unique per account; lowercase letters, digits and single hyphens. |
| result.subdomain | object | Public address of the Worker. |
| result.tags | array<string> | Up to 8 tags. |
| result.observability | object | Observability settings. |
| result.logpush | boolean | Always false: unlike Cloudflare, Logpush is not offered. |
| result.created_on | string | When the Worker was created. |
| result.updated_on | string | When the Worker last changed. |
| result.deployed_on | string | null | When the current deployment became active; null before the first deployment. |
| result.praxis | object | Platform fields: lifecycle status, labels, and soft-delete timestamps. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
# 编辑 Worker
`PATCH /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
Change some fields of a Worker.
**支持状态: supported**
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ---- | ------ | ---- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
## 请求体 (application/json) [#请求体-applicationjson]
必填: true
| 名称 | 类型 | 说明 |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved. |
| tags | array\ | Replaces the tags. |
| observability | object | Observability settings. |
| observability.enabled | boolean | Collect logs. |
| subdomain | object | Subdomain settings. |
| subdomain.enabled | boolean | Serve the Worker on its public subdomain. |
| praxis | object | Praxis settings. |
| praxis.labels | object | Replaces the labels. |
```json
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string",
"description": "Worker name, unique in your account: 3–40 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. The names www, api, admin, app, canary, canary-probe, status, docs and console are reserved.",
"pattern": "^(?!(?:www|api|admin|app|canary|canary-probe|status|docs|console)$)(?!.*--)[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$",
"example": "my-app"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 8,
"description": "Replaces the tags."
},
"observability": {
"type": "object",
"description": "Observability settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Collect logs."
}
}
},
"subdomain": {
"type": "object",
"description": "Subdomain settings.",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Serve the Worker on its public subdomain."
}
}
},
"praxis": {
"type": "object",
"description": "Praxis settings.",
"required": [],
"properties": {
"labels": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Replaces the labels."
}
}
}
}
}
```
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | object | |
| result.id | string | Worker ID, prefixed wkr_. |
| result.name | string | Unique per account; lowercase letters, digits and single hyphens. |
| result.subdomain | object | Public address of the Worker. |
| result.tags | array<string> | Up to 8 tags. |
| result.observability | object | Observability settings. |
| result.logpush | boolean | Always false: unlike Cloudflare, Logpush is not offered. |
| result.created_on | string | When the Worker was created. |
| result.updated_on | string | When the Worker last changed. |
| result.deployed_on | string | null | When the current deployment became active; null before the first deployment. |
| result.praxis | object | Platform fields: lifecycle status, labels, and soft-delete timestamps. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
# 删除 Worker
`DELETE /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}`
Delete a Worker. It can be restored on the native API for 7 days. force is accepted and ignored.
**支持状态: supported**
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ---- | ------ | ---- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | null | No result. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
# 列出版本
`GET /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions`
List versions, newest first.
**支持状态: supported**
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ----- | ------- | ----- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
| page | query | integer | false | Page number, from 1. |
| per\_page | query | integer | false | Items per page (default 20). |
## 响应 [#响应]
### HTTP 200 [#http-200]
Success
**application/json**
| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | boolean | Always true on success. |
| errors | array<any> | Always empty on success. |
| messages | array<any> | Always empty on success. |
| result | array<object> | Versions. |
| result[].id | string | Version ID, prefixed ver_. |
| result[].number | integer | Per-Worker counter (v1, v2, …). |
| result[].created_on | string | When the version was created. |
| result[].main_module | string | null | Entry module name, or null for a version containing only static assets. |
| result[].modules | array<object> | Module names and types; content is never returned. |
| result[].compatibility_date | string | Workers runtime compatibility date. |
| result[].compatibility_flags | array<string> | Runtime compatibility flags. |
| result[].bindings | array<object> | Bindings; secret values are never returned. |
| result[].assets | object | null | Static asset settings. |
| result[].annotations | object | Free-form annotations. |
| result[].author_id | string | null | Who created the version. |
| result[].source | string | Upload origin, e.g. api or sdk. |
| result[].urls | array<string> | Preview URLs of this version. |
| result[].praxis | object | Platform fields: owning Worker, build source, script size and asset manifest summary. |
| result_info | object | Present on list responses. |
| result_info.page | integer | Page number. |
| result_info.per_page | integer | Page size. |
| result_info.count | integer | Items on this page. |
#
`POST /cloudflare/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions`
Upload a version. With deploy=true a deployment starts as well. Static assets are declared with assets.manifest; triggers, migrations, containers and placement are refused.
**支持状态: partial**
Upload a version. With deploy=true a deployment starts as well. Static assets are declared with assets.manifest; triggers, migrations, containers and placement are refused.
## 参数 [#参数]
| 名称 | 位置 | 类型 | 必填 | 说明 |
| ----------- | ----- | ------- | ----- | ----------------------------------------------- |
| account\_id | path | string | true | Any value; your account comes from the API key. |
| worker\_id | path | string | true | Worker ID or name. |
| deploy | query | boolean | false | Also deploy this version. |
## 请求体 (application/json) [#请求体-applicationjson]
必填: true
| 名称 | 类型 | 说明 |
| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| deploy | boolean | Also create a deployment of this version (own face only; on the compatible face use the deploy query parameter). |
| main\_module | string | Entry module name; must equal the name of one of modules. Defaults to the first module; omit it when there are no modules. |
| modules | array\