Praxis 是智能体云平台。API 按服务组织：智能体、模型、沙箱、搜索、自动化，各在自己的前缀下。请求与响应用 JSON，流式响应用 SSE，使用标准的 HTTP 动词与状态码。所有前缀共用一个地址和一个 Key。

基础地址

https://api.deepraxis.com

客户端库

使用服务 API 页列出的客户端库。兼容接口使用对应协议的官方 SDK；自动化提供 TypeScript SDK，本地安装方式见自动化 API。

兼容接口

已经在用 OpenAI、Anthropic、Google、E2B 或 Tavily 的代码，不需要改成 Praxis 的接口：平台提供与这些厂商官方 API 一致的兼容前缀，只改地址就能用。

一个 Key

所有前缀共用在控制台创建的 API Key，随请求放在 Authorization 头里。详见鉴权。

全局约定

• 错误用标准 HTTP 状态码表达类别，错误体按前缀的格式给出原因。详见错误。
• 超出额度返回 429，响应头告诉你何时可以重试。详见限流。
• 版本号写在地址里，弃用提前 90 天以标准头通知。详见版本。
• 关于 API 本身的信息（OpenAPI 描述、健康状态）在 /meta 前缀下。

第一个请求

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}

一个 Key 通所有前缀下的接口。Key 在控制台 → API Key 创建、轮换和吊销；吊销立即生效。

各家 SDK 把 Key 放在哪

你不需要自己拼这个头——官方 SDK 会放；我们同时接受各家 SDK 默认使用的头名。

试一条

curl https://api.deepraxis.com/model/v1/models \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

鉴权失败长什么样

Key 缺失、无效或已吊销，返回 401，错误体按该前缀的格式（见错误）。收到 401 不要重试——换对 Key 再发。

保管

• 只在服务端使用；不要放进浏览器、移动端或公开仓库。
• 用环境变量（示例里的 PRAXIS_API_KEY），不要写进代码。
• 怀疑泄露时在控制台吊销并新建，旧 Key 立即失效。

出错时，HTTP 状态码告诉你错误属于哪一类；错误体按该前缀的格式给出具体原因；每个错误响应还带四个 x-praxis-problem-* 头和一个 x-praxis-recovery-action（限流错误再多带一个 x-praxis-problem-scope，见限流），不论错误体长什么样，重试逻辑只看头就够。

状态码

错误码

以下是常见的机器可读错误码，不是所有端点的封闭枚举。兼容接口的错误体可能使用协议自己的 code/type；跨协议判断可读取 x-praxis-problem-code，其值可能与错误体 code 不同。大小写按返回值区分。

错误体

错误体的格式跟着地址第一段走，和成功响应一致——你的 SDK 不需要为错误特殊处理。

厂商前缀（/openai /anthropic /google /e2b /tavily）：和该前缀对应的官方 API 错误体一模一样。

// /openai
{ "error": { "code": 401, "message": "Invalid API key." } }

// /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。

{
  "type": "https://deepraxis.ai/problems/authentication_error",
  "title": "authentication_error",
  "status": 401,
  "detail": "Invalid API key.",
  "instance": "problem_eqfnxu",
  "code": "AUTHENTICATION_ERROR",
  "retryable": false
}

错误响应头（五个通用头 + 一个限流头）

五个通用头与错误体格式无关；第六个 scope 头仅适用于限流错误：

重试

• retryable 为 true（或状态码 429 502 503）：指数退避重试；429 优先按 retry-after。
• 其它一律不要原样重试——先改请求或 Key。

Praxis 的限流分两层：平台层按你的 Key 限每秒请求数和同时进行的请求数；模型层按模型限每分钟请求数（RPM）和每分钟 token 数（TPM）。每个响应——不论成功还是 429——都带三个 x-ratelimit-* 头，写明当前额度和重置时间，你不需要猜，也不需要为读额度多发请求。

两层限额

两层的 429 都带同样的三个限流头；是哪一层触发的，看错误体的说明（错误）。

平台层：每秒请求数与并发数

默认每个 API Key 每秒最多 5 个请求，同时最多 4 个在途请求。流式请求在流结束前占用并发槽位。超过任一默认限额返回 429，响应带 ratelimit-limit、ratelimit-remaining、ratelimit-reset 和 retry-after；并发超限须等已有请求结束。

实际限额可能因账户而异；以响应头和并发错误详情为准。

三个响应头

x-ratelimit-limit-requests: 5
x-ratelimit-remaining-requests: 4
x-ratelimit-reset-requests: 850ms

同样的三个数也以 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 …"）。

错误体

错误体跟着地址第一段走（见错误）。/model/v1/chat/completions 等原生端点是 Problem Details：

{
  "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 兼容端点：

{ "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 数

限额维度是模型 × 租户 × 分钟，不是 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——等待无效，需要提升该模型的预算。

错误体与状态码见错误；账号额度见配额与限流。

版本号写在地址里，紧跟第一段；每个前缀各自计版本，没有全站统一的版本号。

地址里的版本段

https://api.deepraxis.com/{protocol}/{version}/…

厂商前缀下，版本相关的头（如 Anthropic 的 anthropic-version）原样透传给厂商，行为与官方一致。

什么算破坏性变更

删字段、改字段类型或含义、改默认值、收紧校验、改错误码含义。加字段、加端点、放宽校验不算。

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: </docs/changelog>; rel="deprecation"