1. 接入前准备
开始前应完成快速开始中的账号、余额和密钥步骤，并准备以下信息：
- 一个有效的 API Key。
- 从模型广场或创建密钥页面确认的完整模型代号。
- 与目标模型匹配的密钥分组和足够的账户额度。
- 可以发送 HTTPS 请求的后端或本地开发环境。
不要在浏览器前端暴露密钥网页脚本、公开仓库和客户端安装包都可能被直接读取。生产请求应由自己的服务端发起。
2. 配置 Base URL 与模型代号
站点统一入口是 https://www.codex789.com。使用 OpenAI 兼容 SDK 时，将 Base URL 配置为：
Base URL
https://www.codex789.com/v1请求中的 model 必须使用当前分组提供的调用代号。展示名称与调用代号可能不同，因此不要根据页面标题自行推断。
3. 使用 cURL 验证接口
先用最小请求验证地址、认证和模型分组。将两个占位符替换为自己的值：
cURL
curl https://www.codex789.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [
{"role": "system", "content": "回答保持简洁"},
{"role": "user", "content": "请返回：连接成功"}
],
"stream": false
}'成功响应通常包含生成内容、模型信息和 Token 用量。字段可能随具体模型能力有所不同。
4. Python 接入
安装 SDK：
Terminal
pip install openai把密钥放进环境变量 ISLAND_API_KEY，再运行：
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ISLAND_API_KEY"],
base_url="https://www.codex789.com/v1",
)
response = client.chat.completions.create(
model="MODEL_ID",
messages=[
{"role": "user", "content": "用三点概括今天的任务"}
],
)
print(response.choices[0].message.content)5. Node.js 接入
安装依赖：
Terminal
npm install openai通过环境变量读取密钥：
Node.js
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ISLAND_API_KEY,
baseURL: "https://www.codex789.com/v1",
});
const response = await client.chat.completions.create({
model: "MODEL_ID",
messages: [
{ role: "user", content: "生成一份简短的会议待办" },
],
});
console.log(response.choices[0].message.content);6. 开启流式输出
对话内容较长时，可以设置 stream: true，边接收边展示结果。不同 SDK 的事件读取方式不同，以下是 Python 示例：
Python stream
stream = client.chat.completions.create(
model="MODEL_ID",
messages=[{"role": "user", "content": "写一份商品卖点提纲"}],
stream=True,
)
for chunk in stream:
text = chunk.choices[0].delta.content or ""
print(text, end="", flush=True)生产环境还应配置连接超时、读取超时、取消请求和有限次数的指数退避重试。
7. 常见错误排查
| 状态或现象 | 可能原因 | 处理顺序 |
|---|---|---|
401 | 密钥缺失、复制不完整或已失效 | 检查环境变量和 Bearer 认证头 |
403 | 分组、模型、IP 或有效期限制 | 检查 API 密钥页面中的访问限制 |
404 | 接口路径或模型代号错误 | 确认 Base URL 带 /v1，重新复制模型代号 |
429 | 余额、额度、速率或并发限制 | 查看余额和调用记录，降低并发后重试 |
5xx | 线路或上游暂时异常 | 保留请求信息，有限重试并查看服务状态 |
| 长时间无响应 | 输入过长、网络不稳定或读取超时 | 缩短上下文，增加合理超时并启用流式输出 |
8. 生产环境安全清单
- 开发、测试、生产使用不同 API Key。
- 密钥只存放在服务端环境变量或密钥管理系统。
- 为密钥设置合理的额度、有效期、模型和 IP 限制。
- 日志中屏蔽 Authorization 请求头和用户敏感内容。
- 对
429和临时5xx使用有上限的重试策略。 - 定期查看调用明细，发现异常后立即撤销并轮换密钥。