统一视频 API 的模型选择器:把能力约束做成数据

接入多个视频模型时,只把名称做成下拉框,很容易让用户提交某个型号不支持的时长、画幅或参考素材。比较可靠的做法,是把“模型能力”当成应用中的一份数据契约:选择器负责展示,后端负责按能力校验,请求始终发送模型的完整 ID。

一、用完整 ID 连接目录与调用

无限扩散当前文档列出 GET /v1/models 用于获取模型,视频生成统一使用 POST /v1/videos。显示名称可能调整,调用时应使用文档中的完整 model ID,不要自行把显示名拼成 ID。每次请求还需带 Authorization: Bearer 密钥;密钥应只保存在自己的服务端,不要放到浏览器代码或公开仓库。

二、把约束作为配置,而不是散落在界面里

应用可以维护一份自己的能力配置,例如:

{ id, name, durationOptions, resolutions, ratios, referenceTypes, billingUnit, sourceCheckedAt }

这是应用侧的数据结构示例,不代表 API 返回的 JSON schema。字段值应从所选型号的实时文档读取。页面切换型号时,仅展示该型号允许的参数;服务端提交前再做一次校验,并将不支持的组合明确提示给调用方。

例如,文档当前列出的 seedance-2.5-special2 为 5–30 秒、固定 1080P,支持最多 9 张参考图和 3 条参考音频,不支持参考视频。这个例子只描述该型号,不应推导为所有 Seedance 型号的共同能力。模型和可用性会变化,生产系统应提供“查看实时规格”链接,并记录最近核验时间。

三、将创建任务与处理任务分开

POST /v1/videos 成功后保存返回的 task ID,再通过 GET /v1/videos/{id} 查询同一任务。文档列出的统一状态是 queued、in_progress、completed、failed;建议至少间隔 30 秒轮询。用户刷新页面时从自己的数据库恢复任务,不要因为页面重载再次创建生成请求。

四、成功后再下载并归档

状态为 completed 后,使用 GET /v1/videos/{id}/content 下载结果。文档说明该接口支持 Range,结果有时效,因此下载后应存入自己的对象存储并记录文件大小、媒体信息及任务 ID。不要把临时签名链接当作永久地址。

五、让账单和故障可以追溯

每个任务可记录本地请求 ID、模型 ID、远端 task ID、创建/完成时间、最终状态、计费单位、实际账单金额和产物存储位置。排错日志避免记录 API 密钥或完整提示词。这样在更换型号时,可以区分“能力校验失败”“任务生成失败”和“下载归档失败”,也能按实际账单核对成本。

无限扩散是第三方 API 接入服务,并非 Seedance 上游官方页面。型号能力、价格、可用性和计费以实时 API 文档、模型广场及实际账单为准。接入前请核对:API 文档 https://api.wxksai.com/docs/ ;模型与价格目录 https://api.wxksai.com/pricing 。

reader loved this