只讲接入
不展示套餐、不展示公开价格、不展示固定业务参数。
OpenAI-Compatible · GPT Only
把 GPT 接入写清楚，页面保持干净。
Codex.surf 面向 GPT 模型使用场景。你可以把它理解成一个偏文档化的接入入口： 先在主页获取配置，再按本文档完成 SDK、HTTP 或流式调用。
base_url = "https://your-endpoint/v1"
api_key = "sk-..."
model = "gpt-4.1-mini"
单页结构
可继续扩展
适合 Workers 托管
Overview
概览
本文档默认你已经知道如何使用 OpenAI 风格接口，但不想在公开页面暴露太多业务信息。 所以这里采用“教程优先”的写法：文档侧只保留调用方式、字段说明与排错建议。
兼容 OpenAI 风格
优先覆盖最常见的 SDK 和 `chat/completions` 调用方式。
后续好拆页
章节已经按导航层级分好，后续可以直接拆成多页知识库。
Checklist
接入前准备
1
获取专属接入信息
在 Codex.surf 主页获取你的密钥、接入域名与可用模型名。
2
确认调用路径
推荐优先使用 OpenAI 兼容路径，通常以 `/v1/...` 结尾。
3
把敏感信息放进环境变量
不要把密钥直接写死在仓库里，尤其是示例项目或前端代码中。
4
优先使用后台给出的模型 ID
模型名不要猜，直接使用主页或后台返回的可用 ID。
Quick Start
快速开始
推荐做法：
先把 `API Key`、`Base URL`、`Model` 全部写进环境变量，再在代码里读取。
环境变量示例
CODEX_SURF_API_KEY=sk-xxxxxxxx
CODEX_SURF_BASE_URL=https://your-endpoint/v1
CODEX_SURF_MODEL=gpt-4.1-mini
Python / OpenAI SDK
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("CODEX_SURF_API_KEY"),
base_url=os.getenv("CODEX_SURF_BASE_URL"),
)
response = client.chat.completions.create(
model=os.getenv("CODEX_SURF_MODEL", "gpt-4.1-mini"),
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "用一句话介绍 Codex.surf。"},
],
)
print(response.choices[0].message.content)
Node.js / OpenAI SDK
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.CODEX_SURF_API_KEY,
baseURL: process.env.CODEX_SURF_BASE_URL,
});
const completion = await client.chat.completions.create({
model: process.env.CODEX_SURF_MODEL || "gpt-4.1-mini",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "给我一个接入建议。" },
],
});
console.log(completion.choices[0].message.content);HTTP Examples
接口示例
如果你不想先上 SDK，可以直接从 HTTP 调用开始。下面给的是最常见的两种形式：普通响应和流式响应。
cURL / 普通响应
curl https://your-endpoint/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CODEX_SURF_API_KEY" \
-d '{
"model": "gpt-4.1-mini",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "请写一段 30 字以内的欢迎语。"}
]
}'
cURL / 流式响应
curl https://your-endpoint/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CODEX_SURF_API_KEY" \
-d '{
"model": "gpt-4.1-mini",
"stream": true,
"messages": [
{"role": "user", "content": "请分三点介绍如何快速接入。"}
]
}'路径建议
优先从 `/v1/chat/completions` 开始。如果你后续需要更多兼容接口，再按业务逐步扩展。
鉴权建议
`Authorization: Bearer <API_KEY>` 保持不变，这样后续更换 SDK 时迁移成本最低。
调试建议
首次联通时先关掉复杂参数，只保留 `model` 和 `messages`，确认 200 响应后再加温度、流式等选项。
Models
模型说明
Codex.surf 当前聚焦 GPT 模型，所以文档不做跨厂商接口说明。你只需要记住两个原则：
- 模型 ID 以你在主页拿到的实际值为准，不要依赖猜测出来的别名。
- 如果同一账号下会切不同模型，优先把模型名抽成环境变量，而不是在项目里写死。
- 首次接入时建议先用稳定、轻量的默认模型完成联调，再逐步切到更高规格模型。
FAQ
常见问题
返回 401，通常是什么原因？
优先检查 API Key 是否填错、是否多了空格，以及请求头是否使用了 `Bearer` 前缀。
返回 404，应该先排查哪里？
先看 Base URL 是否带了正确的 `/v1`，再检查调用路径有没有拼错，最后确认域名是否就是你主页拿到的接入地址。
流式输出没有内容，可能是什么问题？
先确认客户端确实在消费 SSE/流式响应；很多问题不是接口没返回，而是调用端没有按流模式读取数据。
为什么文档里没有公开固定模型列表？
这是有意为之。本文档只负责教程，具体可用模型以你的主页或后台配置为准，这样页面更干净，也方便后续调整。
Why Codex.surf
为什么是 Codex.surf
文档入口更克制
不把页面写成产品海报，先让开发者完成接入，转化动作统一回到主页承接。
聚焦 GPT 场景
内容不混杂，少掉不必要的跨模型说明，能显著降低首次阅读成本。
后续维护轻
单页先跑起来，后面不论加章节、删章节还是拆分页，结构都已经留好了。
Next Step
下一步
需要真实接入信息时，回到主页获取。
文档页负责解释“怎么接”，主页负责承接“去哪里拿配置”。这样页面边界会更清楚。