OpenAI 兼容 · 多模型统一接入

EToken API 文档

EToken 提供 OpenAI 兼容的 API，面向生产接入统一调用聊天补全、图片生成和视频生成模型，并在控制台追踪 Token、费用、Credits 抵扣、现金补扣和 Request ID。

创建 API Key 打开 API 调试器

Base URL

/api/v1

认证方式

Bearer ak_xxx.sk_xxx

协议兼容

OpenAI Compatible

Quick Start

快速开始

主流平台的文档首屏会优先回答「怎么跑通第一条请求」。这里按真实生产接入顺序组织，让开发、财务和运维都能找到下一步。

Step 1

创建 API Key

在控制台创建生产 Key，并配置额度、过期时间和 IP 白名单。

Step 2

选择模型

在模型市场查看上下文、价格、限流和工具能力，确认模型适合业务场景。

Step 3

发起首次调用

使用 OpenAI 兼容协议调用 /v1/chat/completions，建议先在 API 调试器验证。

Step 4

查看用量与排障

通过 Request ID 追踪 Token、费用、Credits 抵扣、现金补扣和错误信息。

Examples

替换凭据即可运行的代码示例

示例保持 OpenAI SDK 兼容写法。先把 ETOKEN_API_KEY 设置为控制台创建 Key 后返回的完整 Bearer Token，再发起首次非流式调用。

API Key 格式

ETOKEN_API_KEY 应填写完整值 ak_xxx.sk_xxx，包含 Access Key ID、英文句点和 Secret Key。不要只填写 Access Key ID。

export ETOKEN_API_KEY="ak_xxx.sk_xxx"

curl /api/v1/chat/completions \
  -H "Authorization: Bearer $ETOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [
      {"role": "system", "content": "你是企业知识库助手。"},
      {"role": "user", "content": "用三句话说明 EToken API 的接入步骤。"}
    ],
    "stream": false,
    "max_tokens": 512
  }'

Auth

认证与安全

业务调用接口必须携带 Authorization Header。/v1/models 和 /v1/health 可用于公开检查模型列表和服务状态。

请求头格式为 Authorization: Bearer ak_xxx.sk_xxx。完整 API Key 只在创建时展示一次，后续只能查看脱敏值；生产 Key 建议绑定 IP 白名单、额度上限和过期时间，并通过环境变量注入。

最小权限

为不同应用拆分 Key，避免一个 Key 覆盖所有场景。

额度保护

配置日额度或月额度，防止异常循环调用。

审计留痕

关键变更会进入操作日志，便于追踪谁改了配置。

Chat Completions

聊天补全

核心接口为 POST /v1/chat/completions，支持非流式与流式输出。JSON mode、工具调用和联网搜索以模型市场能力矩阵为准。

POST /v1/chat/completions

参数	类型	必填	说明
model	string	是	模型名称，建议直接复制模型市场中的 model ID。
messages	array	是	对话消息列表，支持 system、user、assistant、tool 角色。
stream	boolean	否	是否开启 SSE 流式输出，默认 false。
temperature	number	否	采样温度，建议生产场景保持 0.2-0.8。
max_tokens	number	否	最大输出 Token 数，不得超过模型最大输出限制。
response_format	object	否	JSON mode，例如 {"type":"json_object"}。
tools	array	否	OpenAI 兼容工具定义，需选择支持 Tools 的模型。
web_search	boolean	否	联网搜索能力，是否可用取决于模型能力矩阵。

Models

模型与价格

模型市场是 API 选型的事实来源。建议接入前确认模型 ID、上下文、最大输出、价格、限流和能力标签。

qwen3.7-max

Qwen · text

上下文 1,000,000 Token

查看价格

字段	类型	说明
capabilities	object	模型能力矩阵，包含 streaming、multimodal、tools、jsonMode、reasoning、webSearch。
max_output_tokens	number	模型建议最大输出 Token 数，业务侧 max_tokens 不应超过该值。
latency_range	string	生产延迟参考区间，用于排期、超时和重试策略。
response_format	object	JSON mode 请求参数，需选择支持 JSON mode 的模型后启用。

Errors

错误码与限流

错误处理需要记录 Request ID、模型、API Key、请求时间、Token 和费用信息。

状态码	含义	处理建议
401	认证失败	API Key 缺失、无效或已过期。
403	无权限	Key 无权访问指定模型、Agent 或组织资源。
404	模型不存在	模型名称错误、已下线或未向当前账号开放。
429	触发限流	请求频率或并发超过限额，可降低并发或申请提额。
500	服务异常	平台内部错误，请记录 Request ID 后重试或联系支持。
503	模型暂不可用	上游模型繁忙、维护或路由不可用。

Billing

计费与支付帮助

EToken 的调用记录不仅记录 Token，也会记录 API Key、计费、资源包、对公转账、发票、退款、错误码、限流和数据安全相关字段。财务核对与技术排障都应从 Request ID 开始。

字段	字段位置	说明
Token 用量	响应 usage.prompt_tokens / usage.completion_tokens / usage.total_tokens	用于语言模型计费、上下文分析和费用明细。
平台费用	响应 _cost；调用记录 rmbCost / cost	非流式响应会返回平台估算费用，最终账单以调用记录为准。
调用延迟	响应 _latency；调用记录 latency	用于定位上游渠道、网络和模型响应耗时。
Credits 抵扣	调用记录 billingBreakdown.creditsDeducted	优先使用企业 Token Plan 或资源包 Credits 抵扣。
现金补扣	调用记录 billingBreakdown.cashDeducted	Credits 不足且开启余额兜底时，从现金余额继续扣费。
Plan 系数	调用记录 billingBreakdown.effectiveCoefficientBps	不同 Token Plan 可按模型市场标价折算。
Request ID	响应头 x-request-id / 响应体 request_id	排障、账单核对和客服定位的首要凭据。

费用分析建议

先按 Request ID 定位单次调用，再查看 API Key、模型、Token、费用、Plan 系数、Credits 抵扣和现金补扣；支付问题核对对公转账与退款状态，开票问题核对发票资料和接收邮箱，安全问题继续进入操作日志核对。

调用记录用量成本

Checklist

生产接入清单

上线前需要验证接口返回、权限、限流、预算、排障和财务对账能力。

接口

完成流式、非流式、超时、重试和 JSON mode 验证。

权限

Key 按应用拆分，开启额度、过期时间和 IP 白名单。

成本

确认 Token、Credits 抵扣、现金补扣和预算告警能被追踪。

排障

日志记录 Request ID，调用记录可复制排障包。

FAQ

常见问题

这些问题来自开发接入、财务核对和生产排障的高频场景。

是否兼容 OpenAI SDK？

兼容。将 SDK 的 baseURL 指向 EToken /api/v1，并使用平台 API Key 即可。

生产环境应该先接哪个接口？

建议先用 /v1/models 和 /v1/health 确认可用模型与服务状态，再接 /v1/chat/completions、调用记录、用量成本和预算告警。

如何核对费用？

在调用记录中按 Request ID 查看 Token、费用、Plan 系数、Credits 抵扣、现金补扣和扣费来源。

如何排查 429？

查看当前模型限流、API Key 额度、调用并发和预算阈值；必要时申请提额。