几步，完成第一次调用
One Arena 提供 OpenAI 兼容的文本对话接口。先创建 API Key，再将 SDK 的 base URL 指向当前站点。
import os, uuid
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONE_ARENA_API_KEY"],
base_url="https://your-one-arena.example/v1",
)
# Only use models available from this gateway.
models = client.models.list().data
if not models:
raise SystemExit("No models connected. Contact the administrator.")
model_id = os.environ.get("ONE_ARENA_MODEL", models[0].id)
if model_id not in {model.id for model in models}:
raise SystemExit("ONE_ARENA_MODEL is not available on this gateway.")
request_id = str(uuid.uuid4()) # Reuse for retries of this request.
response = client.chat.completions.create(
model=model_id,
messages=[{"role": "user", "content": "你好，One Arena！"}],
max_tokens=256,
extra_headers={"Idempotency-Key": request_id},
)
print(response.choices[0].message.content)Python 安装：pip install openai；JavaScript 安装：npm install openai。请在服务端使用示例并通过环境变量读取密钥。示例先读取可用模型；列表为空时会停止，不发起生成或扣费。Python / JavaScript 可用 ONE_ARENA_MODEL 指定列表中的模型。cURL 示例适用于 Bash / zsh，并需要 jq 与 Python 3。
身份认证
控制台登录 / 创建账户。API 请求通过 Authorization: Bearer 传入 One Arena Key。密钥仅在创建时完整展示，服务端只保存哈希。
浏览器通过安全会话访问控制台。应用服务通过独立 API Key 调用网关；在控制台撤销密钥后，该密钥会立即失效。
Authorization: Bearer oa_…模型列表
GET /v1/models使用 API Key 认证，返回管理员已配置的对话模型。目录同时展示图像、视频、音频生成与多模态理解模型。媒体生成适配器尚未开放，媒体模型不会通过 /v1/chat/completions 调用。展示模型不代表已接通服务。
统一对话调用
POST /v1/chat/completions| 参数 | 说明 |
|---|---|
| model | 必填，已配置模型 ID |
| messages | 必填，1–30 条文本消息，支持 system / user / assistant，总输入不超过 32 KB |
| temperature | 可选，0–2，默认 0.7 |
| max_tokens | 1–4096，默认 1024 |
| stream | 首版支持 false；流式调用待开放 |
为每个逻辑请求设置唯一 Idempotency-Key（1–100 位字母、数字或 . _ : -）。重试相同请求时复用该值，避免重复扣费。相同幂等键不可用于不同参数。
当前网关提供文本输入，即使目录模型具备多模态理解能力，图像、音频与视频输入仍需单独适配与验证。暂不支持 tools、functions、response_format。默认每用户每分钟最多 30 次、每天最多 10,000 次请求，上游超时为 45 秒。
错误处理
错误响应采用 {"error":{"code":"…","message":"…"}} 结构。上游密钥和内部错误详情不会回传给客户端。
| HTTP 状态 | 处理方式 |
|---|---|
| 400 | 检查参数、模型标识和请求大小 |
| 401 | 检查登录状态与 API Key 是否有效 |
| 402 | 余额不足以预留本次最大用量，申请充值或降低输出上限 |
| 409 | 幂等请求冲突、已失败或请求处理中；先核对调用记录 |
| 429 | 达到速率限制，稍后重试 |
| 503 | 上游未配置或暂时不可用 |
| 502 | 上游响应异常或超时，本次未收费 |
可核对的计费
用量根据上游返回的实际 Token 计算。余额采用整数微美元（1 USD = 1,000,000 微美元），调用前预留上限金额，完成后按实际费用结算并返还差额。失败请求不产生消费。
用量记录保留请求编号、模型、输入与输出 Token、耗时、费用和状态。演示内容不进入消费账本。人工充值需由管理员核实实际款项后入账。
充值与订单接口
充值接口使用控制台登录会话，写操作校验同源请求。模型 API Key 仅用于模型调用，不能操作充值。所有金额以 USD 表示，单笔 $1–$10,000，最多两位小数。
| 接口 | 用途 |
|---|---|
GET /api/payments/orders | 查询在线支付配置、模式与自己的最近 100 笔订单 |
POST /api/payments/orders | 创建 Stripe Checkout 订单，返回 checkoutUrl |
GET /api/payments/orders/:id | 查询自己的订单状态，以 paid 确认入账 |
GET /api/topups | 查询人工充值是否开放、收款说明与历史申请 |
POST /api/topups | 提交人工充值申请，状态为 pending |
GET /api/topups/:id | 查看自己的申请及处理说明 |
DELETE /api/topups/:id | 取消自己的待处理申请 |
两种创建接口均需 Idempotency-Key 请求头，正文为 {"amount":10,"currency":"USD"}。同一申请重试应复用幂等键及金额；金额变更需新键。同一用户重复提交同一申请只保留一份订单。
在线支付订单由已验证的服务端回调入账，浏览器返回地址不作为付款依据。商户未配置时返回 503 payment_not_configured；人工收款说明未配置时暂停新申请。创建订单或提交申请均不会直接增加余额。
人工申请状态：pending（待核实）、approved（已入账）、rejected（已拒绝）、canceled（已取消）。管理员通过 /api/admin/topups 查询并处理申请，确认入账时必须提供实际收款流水号；拒绝时必须填写用户可见的说明。
支付回调的签名校验、币种及金额核对、幂等入账均由服务器完成。切勿在前端持有商户密钥。充值操作请前往余额与账单。