# OpenAI 兼容接口 (/docs/cloud/services/model/guides/openai-compatible)



OpenAI SDK 使用 `https://api.deepraxis.ai/openai/v1`。请求按同协议转发；兼容不表示所有官方端点、字段和模型都可用。

## 选对地址 [#选对地址]

| 客户端              | 基础地址                                 | 模型目录                                                   |
| ---------------- | ------------------------------------ | ------------------------------------------------------ |
| OpenAI SDK       | `https://api.deepraxis.ai/openai/v1` | `/openai/v1/models`                                    |
| Anthropic SDK    | `https://api.deepraxis.ai/anthropic` | `/anthropic/v1/models`                                 |
| Google GenAI SDK | `https://api.deepraxis.ai/google`    | `/google/v1beta/models`                                |
| Praxis 原生 API    | `https://api.deepraxis.ai/model/v1`  | 见[原生 API](/docs/api/native/model)，包含 `providerOptions` |

各兼容目录只列声明提供该协议的模型。出现在 OpenAI 目录里不等于同时支持 Chat Completions 和 Responses；未声明的操作返回 `404 model_protocol_not_offered`。

## 字段差异去哪里核对 [#字段差异去哪里核对]

| 应用使用的内容                   | 发请求前核对                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| `messages`、工具、采样、思考、供应商偏好 | [Chat Completions 字段支持](/docs/api/compatible/openai/createChatCompletion)                         |
| `input`、响应存储、响应工具         | [Responses 字段支持](/docs/api/compatible/openai/createResponse)                                      |
| `usage.cost`、生成 ID        | [迁移页费用处理](/docs/cookbook/migration/from-openai#行为差异)与[生成记录](/docs/api/native/model/getGeneration) |
| 上传、文件用途                   | [上传文件](/docs/api/compatible/openai/createFile)                                                    |
| 对话以外的端点                   | [操作支持情况](/docs/api/compatible/openai)与[不支持清单及替代](/docs/cookbook/migration/from-openai#不支持的端点与替代)  |

未知顶层字段可能原样转发给同协议上游；请求被接受不证明字段已生效。已声明字段仍会校验。依赖一个选项前，请查看对应端点的字段支持说明。

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 验证 Responses [#2-验证-responses]

示例使用 `deepseek-flash`。截至 2026-10-12，`glm-5.3-flash` 也提供 Responses；`gpt-5.6-sol` 提供 Chat Completions，但不提供 Responses。使用前在[模型目录](https://console.deepraxis.ai/models)确认所需操作。

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.responses.with_raw_response.create(
    model="deepseek-flash",
    input="Reply OK.",
    max_output_tokens=1024,
)
reply = raw.parse()
text = reply.output_text
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

期望：`output_text` 是最终正文，不把思考输出当作正文。若返回 `model_protocol_not_offered`，换支持 Responses 的模型；若提示 `does not exist`，从目录复制准确 ID。已有应用回滚时同时恢复原地址、Key 与模型，再运行原冒烟请求。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook：从 OpenAI 迁移 →](/docs/cookbook/migration/from-openai)