模型接口接入说明

V1.1 · 同一个模型的不同渠道遵循同一份原厂接口标准。

首批部署 7 个独立适配器，覆盖 DeepSeek V4 Pro、GPT Image 2.5 Sunburst、Seedance 2.0 Fast 和标准版。实际调用还需有效上游凭据、模型权限和余额；后台“模块就绪”不代表该账号已通过真实调用。

入口与鉴权

平台地址 + /model-api/{平台模型 ID} + 官方路径
GET /api/models

模型列表只返回 Key 已授权且启用的模型，按该 Key 设置的排序展示。callable 表示至少一个适配器和凭据已配置，不保证上游权限、余额或实时并发充足。

使用平台 Key：Authorization: Bearer … 或 x-api-key: …（也保留 x-goog-api-key）。多个鉴权头的 Key 不一致时拒绝，不能在查询串中携带 Key。来源 IP 必须符合 Key 配置。路径中的平台模型和正文中的官方 model 必须匹配。

用户测试与用量回执

打开用户侧测试台。使用平台 Key 调用正式接口；真实生成按用量扣额。后台模型渠道行的“实测”可创建只授权一个路由的普通测试 Key；GET /api/models?test_route=路由ID 只校验该模型是否仅授权此路由，不提供选路绕过。多路由授权返回 409，目标未授权返回 404。

GET /api/requests/{X-Request-ID}/receipt
Authorization: Bearer <发起原请求的同一个平台 Key>

回执只读，同样校验 Key 和来源 IP。请求不存在或属于其他 Key 均返回 404。包含原请求与生成请求 ID、模型、状态、任务 ID、结算状态、已确认输入输出 tokens、预占及计量来源。视频查询回执关联原生成账单，重复查询不会产生新的生成费用。

confirmed_tokens 为已确认扣额；reserved_tokens 为未释放预占；total_tokens 仅在全部尝试已结算时返回最终数值，否则为 null。settlement_status 为 held、pending、settled 或 not_started；usage_sources 和 formula_versions 返回计量来源及固定的公式版本。回执 HTTP 200 不代表原生成成功。

视频刷新后可用原 Key 和任务 ID 继续查询；“停止等待”不等于取消生成。生成成功、结果播放和费用结算分别展示；媒体地址可能因到期或网络限制无法播放。

首批接口

平台模型	官方路径 / 正文 model	已实现能力
deepseek-v4-pro	POST /v1/chat/completions（也支持 /chat/completions） deepseek-v4-pro	文本同步与 SSE；thinking、工具调用结构；原生 Chat 响应和 usage。
gpt-image-2.5-sunburst	POST /v1/images/generations gpt-image-2.5-sunburst	同步文生图，base64 结果；n、size、quality、输出格式等由适配器校验。
seedance-2.0-fast	POST /api/v3/contents/generations/tasks doubao-seedance-2-0-fast-260128	异步视频任务；4SToken、IP 视频渠道。
seedance-2.0	POST /api/v3/contents/generations/tasks doubao-seedance-2-0-260128	异步视频任务；4SToken 渠道。

文本、图片分别提供 API易与眸析云适配器。请求时无需选择渠道，平台只在同一模型的候选渠道中调度。各渠道底座型号依据渠道声明，不能由代理接口独立证明。

请求示例

POST /model-api/deepseek-v4-pro/v1/chat/completions
Authorization: Bearer <平台 Key>
Content-Type: application/json

{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"你好"}],"thinking":{"type":"disabled"},"max_tokens":64,"stream":true,"stream_options":{"include_usage":true}}

POST /model-api/gpt-image-2.5-sunburst/v1/images/generations

{"model":"gpt-image-2.5-sunburst","prompt":"白色背景上的蓝色圆形","size":"1024x1024","quality":"low","n":1}

POST /model-api/seedance-2.0-fast/api/v3/contents/generations/tasks

{"model":"doubao-seedance-2-0-fast-260128","content":[{"type":"text","text":"白云在蓝天中缓慢移动"}],"duration":5,"ratio":"16:9","resolution":"720p","generate_audio":false,"watermark":false}

响应：{"id":"task_..."}

GET /model-api/seedance-2.0-fast/api/v3/contents/generations/tasks/task_...
Authorization: Bearer <创建任务时的同一个平台 Key>

首批视频要求明确 duration（4–15 秒）、ratio、resolution（480p/720p/1080p）、generate_audio、watermark，避免不同渠道的默认值产生偏差。content 支持一个文本块及 HTTP(S) URL 参考图、视频、音频或首尾帧；角色和组合由适配器验证，具体模型能力以上游为准。IP 渠道暂不支持 seed。

视频生命周期

创建成功后返回平台任务 ID，并持久保存上游任务 ID、原渠道、适配器版本及计量快照。后台每隔至少 3 秒查询原任务；调用方也可用同一 Key 查询。任务状态为 queued、running、succeeded、failed 等，成功地址位于 content.video_url。只允许任务所属 Key 和模型访问。

查询失败不会再次生成，也不会切换渠道重建任务。服务重启后恢复查询已受理任务。已受理任务使用原渠道配置快照；变更优先级或停用新请求路由不会转移历史任务。原适配器版本不可用时保留任务，恢复该版本后继续查询。当前不支持任务取消、回调、素材库与文件上传。

响应、重试与切换

适配器内部处理渠道差异，返回该模型的官方结构；不会把图片、视频包装为 Chat Completions。X-Request-ID 仅用于追踪，不写入正文。客户端凭据、Cookie 和传输层头不会转发给上游。

只在当前 Key 的指定模型下，按其独立配置的渠道优先级、同级排序号、固定路由 ID 选择。没有配置或启用渠道时返回不可用；公共目录顺序的变化不会改变已保存的 Key 配置。平台 tokens 余额不足或本地并发已满直接跳过。每渠道首次调用加最多 3 次重试，仅用于连接建立失败等明确未执行的故障。接收超时、提交结果未知或流式交付中断不会自动重发。已输出流式内容后不能切换渠道。

正常收到的业务错误（包括 HTTP 200 内的 error 或渠道 code/msg）直接返回并记录，不重试、不切换。HTTP 429 也不会被笼统视为可重试故障；只有适配器明确证明未执行且为容量限制时才允许直接换路。首批未给未经确认的上游错误码配置容量切换。

平台 HTTP / 错误码	处理
400 · invalid_json / unsupported_parameters	输入无效或没有渠道支持这些参数；未发送上游。
401 / 403 · invalid_api_key / model_not_allowed / ip_not_allowed	检查平台 Key、模型授权与 IP。
413 · payload_too_large	入站 JSON 超过 1 MiB；保留拒绝元信息。
503 · channel_not_connected / no_available_channel	检查模块、凭据、授权、余额与并发。
503 · execution_unknown	按请求 ID 核对上游执行结果，禁止盲目重发。
404 · task_not_found	任务不存在、模型不符或不属于该 Key。

原厂协议的错误字段由相应适配器输出；尚未部署的模型使用平台保留错误格式。

tokens、单价和日志

每个 Key × 模型 × 渠道独立记录 tokens 余额，没有重置周期，由管理员手动补额。请求前原子预占 tokens 和并发；确认执行与用量后结算一次，释放剩余预占。执行未知时保留并发和余额占用；已结束但用量未知时只保留余额预占，由管理员核实结算。预占是估算，实际消费超出时如实记录欠额。

可信上游 usage 优先，也可设置平台公式。文本按字符和消息结构估算；图片按数量、实际像素与品质系数；视频按上游报告的秒数、分辨率以及输入参考素材数量估算。4SToken 缺少结果规格时采用已成功请求的明确时长和分辨率，日志标记 successful_request_spec；该值是平台记账规格，不是媒体测量值。后台可修改所有系数并保留版本；历史请求、重试和视频查询沿用创建时的版本。平台估算不是原厂 tokenizer，绝不写回或伪造官方 usage。无法确认实际媒体计量信息时转人工核实。

费用统计可选元 / 百万输入输出 tokens、元 / 张或元 / 视频秒，与 tokens 余额分别管理。单价需管理员填写；初始 0 表示尚未配置，不能作为上游免费或供应商账单依据。

保存请求、实际发送和接收报文、最终响应、流式数据、任务查询和原始用量。凭据脱敏。大报文以摘要关联私有文件，可在管理员请求详情下载；上游响应上限 64 MiB，文本流上限 8 MiB。首版日志不自动清理。

范围与原厂文档

本批未开放图片编辑和图片流式、文件上传、语音、音乐及其余目录模型的真实执行。SDK 完整兼容性需逐个 SDK 验收，本版验证的是 HTTP 原生接口与上述能力子集。