OpenAI 兼容 · 多模型统一接入
EToken API 文档
EToken 提供 OpenAI 兼容的 API，面向生产接入统一调用聊天补全、图片生成和视频生成模型，并在控制台追踪 Token、费用、Credits 抵扣、现金补扣和 Request ID。
Base URL
/api/v1
认证方式
Bearer ak_xxx.sk_xxx
协议兼容
OpenAI Compatible
Quick Start
快速开始
按照以下步骤完成第一次 API 调用。
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。
不要根据模型名称猜生成能力
先读取 /v1/media/models。同一模型支持的生成方式在 parameters.generationModes，素材类型在 parameters.referenceTypes，最大素材数在 parameters.maxReferences；按生成方式的总数、图片/视频/音频上限和音频独用规则在 parameters.referenceRulesByMode，应优先使用当前方式对应的规则。目录未返回的方式不会受理，也不会产生扣费。
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
Media Jobs
图片、视频、音频与音乐生成
多媒体生成统一使用异步任务 API。先读取模型目录和参数默认值，再获取报价，确认后创建任务，最后通过任务 ID 查询状态和作品。
模型名称怎么填写
请求中的 model 使用上游约定的公开型号，例如 doubao-seedance-2-0-mini-260615。不要使用数据库 CUID，也不要使用历史导入名。若一个型号同时支持图片和视频，使用 type 区分。
完整 cURL 流程
export ETOKEN_API_KEY="ak_xxx.sk_xxx"
# 1. 获取可调用型号；请求时复制 model 字段，不要使用数据库记录 ID
curl /api/v1/media/models \
-H "Authorization: Bearer $ETOKEN_API_KEY"
# 2. 取得报价（此步骤不扣费）
QUOTE=$(curl -s /api/v1/media/quote \
-H "Authorization: Bearer $ETOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-mini-260615",
"type": "video",
"prompt": "晨光中的湖面，固定镜头，轻微水波",
"ratio": "16:9",
"resolution": "720p"
}')
# 3. 使用同一输入和报价版本创建任务；幂等键重试时必须保持不变
curl /api/v1/media/jobs \
-H "Authorization: Bearer $ETOKEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: media-demo-20260921-0001" \
-d "$(jq -n --argjson q "$QUOTE" '{
input:{model:"doubao-seedance-2-0-mini-260615",type:"video",prompt:"晨光中的湖面，固定镜头，轻微水波",ratio:"16:9",resolution:"720p"},
quoteVersion:$q.data.version,
deductionVersion:$q.data.deductionVersion
}')"
# 4. 使用上一步返回的任务 id 查询结果
curl /api/v1/media/jobs/TASK_ID \
-H "Authorization: Bearer $ETOKEN_API_KEY"幂等重试
同一次生成的重试必须复用同一个 Idempotency-Key；更换参数时必须使用新键。
异步状态
queued、processing 表示生成中；archiving 表示已生成、正在保存。delivery_failed 表示生成成功但交付异常，unknown 表示需核对；均请保留原任务，不要重复生成。
交付进度
主异步链的 delivery 字段提供保存阶段、重试次数和安全错误码；暂时故障自动限次重试，停止重试后联系管理员恢复原任务。
最终账单
quote 是提交前预计，实际扣费、Credits 和现金拆分以任务详情及调用记录为准。
Models
模型与价格
调用前请确认模型 ID、支持的参数与价格。
Errors
错误码与限流
错误处理需要记录 Request ID、模型、API Key、请求时间、Token 和费用信息。
Billing
计费与支付帮助
通过 Request ID 查询调用状态、用量和费用，定位异常请求。
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 额度、调用并发和预算阈值；必要时申请提额。