Quickstart
本指南帮助新用户在不联系客服的情况下完成第一次 Codexpertise API 请求。
TODO: verify against sub2api。以下示例使用 OpenAI-compatible 的
POST /v1/chat/completions 请求形态。如果 dashboard 显示了不同的首次调用
endpoint，请保留相同的 API base URL 和 bearer token 写法，并使用 dashboard
显示的 endpoint。
1. 注册或登录
访问 dash.codexpertise.com 注册或登录。请使用 拥有目标额度或计费计划的账号进行测试。
2. 创建 API Key
在 dashboard 的 API key 区域创建一个新的本地测试 key。只复制一次，保存到安全
位置。下面所有示例统一使用 YOUR_API_KEY 作为占位符。
3. 设置 API Base URL
API 客户端统一使用：
https://api.codexpertise.com
本地测试前先设置环境变量：
export CODEXPERTISE_API_KEY="YOUR_API_KEY"
export CODEXPERTISE_BASE_URL="https://api.codexpertise.com"
export CODEXPERTISE_MODEL="YOUR_MODEL"
YOUR_MODEL 请替换成你的账号或套餐可用的模型名称。生产模型目录完成验证前，
本文不会列出未经确认的模型列表。
4. 使用 curl 发起请求
curl -sS "$CODEXPERTISE_BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $CODEXPERTISE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"messages": [
{
"role": "user",
"content": "Say hello in one short sentence."
}
]
}'
成功时会返回 relay 的 JSON 响应。如果收到错误，先查看下方常见错误，再决定是否 轮换 key 或提交支持请求。
5. 使用 Node.js 发起请求
此示例使用当前 Node.js 内置的 fetch，不需要额外依赖。
const apiKey = process.env.CODEXPERTISE_API_KEY;
const baseURL = process.env.CODEXPERTISE_BASE_URL ?? "https://api.codexpertise.com";
const model = process.env.CODEXPERTISE_MODEL;
if (!apiKey || !model) {
throw new Error("Set CODEXPERTISE_API_KEY and CODEXPERTISE_MODEL first.");
}
const response = await fetch(`${baseURL}/v1/chat/completions`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model,
messages: [
{
role: "user",
content: "Say hello in one short sentence."
}
]
})
});
const body = await response.text();
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${body}`);
}
console.log(JSON.parse(body));
运行方式：
CODEXPERTISE_API_KEY="YOUR_API_KEY" \
CODEXPERTISE_BASE_URL="https://api.codexpertise.com" \
CODEXPERTISE_MODEL="YOUR_MODEL" \
node quickstart.mjs
6. 使用 Python 发起请求
此示例只使用 Python 标准库，不需要安装额外包。
import json
import os
import urllib.request
api_key = os.environ["CODEXPERTISE_API_KEY"]
base_url = os.environ.get("CODEXPERTISE_BASE_URL", "https://api.codexpertise.com").rstrip("/")
model = os.environ["CODEXPERTISE_MODEL"]
payload = {
"model": model,
"messages": [
{
"role": "user",
"content": "Say hello in one short sentence.",
}
],
}
request = urllib.request.Request(
f"{base_url}/v1/chat/completions",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request, timeout=60) as response:
print(json.dumps(json.loads(response.read()), indent=2))
运行方式：
CODEXPERTISE_API_KEY="YOUR_API_KEY" \
CODEXPERTISE_BASE_URL="https://api.codexpertise.com" \
CODEXPERTISE_MODEL="YOUR_MODEL" \
python3 quickstart.py
7. 配置 Codex CLI 或 coding agent
许多 coding agent 支持 OpenAI-compatible 环境变量。先使用占位符完成配置， 确认可用后再把值放入 shell profile、CI secret store 或本地 secret manager。
export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.codexpertise.com"
export OPENAI_MODEL="YOUR_MODEL"
如果你的 agent 使用配置文件而不是环境变量，可以保留同样的值：
api:
base_url: "https://api.codexpertise.com"
api_key: "YOUR_API_KEY"
model: "YOUR_MODEL"
TODO: verify against sub2api，并结合具体 Codex CLI 或 coding-agent 客户端版本 确认后，再把客户端专用配置字段写成稳定契约。
常见错误
401 Unauthorized
API key 缺失、格式错误、已过期，或复制时带入了多余空格。确认请求中包含
Authorization: Bearer YOUR_API_KEY，并已将占位符替换成真实 key。
403 Forbidden
Key 有效，但账号、套餐、来源或 route 没有权限访问当前 API。请检查 dashboard 权限、额度归属，以及该 route 是否已对你的套餐开放。
429 Rate Limited
账号超过了速率限制或额度窗口。等待一段时间后重试，减少并发请求，并在 dashboard 中检查用量。
5xx Upstream Error
Relay 或上游 provider 返回了服务端错误。请使用 backoff 重试。如果问题持续，
记录时间和 request ID，但不要分享原始 API key 或完整 Authorization header。
Streaming interrupted
流式响应被客户端、网络、代理、超时或上游 provider 中断。可以先重试一次，再测试 非 streaming 请求，并尽量减少响应长度。
安全提醒
- 不要把 API key 提交到 git。
- 本地和生产环境都应使用环境变量或 secret manager。
- 如果 key 泄露，请立即在 dashboard 中轮换，并从日志、工单、截图和仓库历史中 移除泄露值。