视频模型与参考素材合同

视频任务统一经过素材归属检查、能力检查、素材读取、协议适配、任务轮询和结果保存。模型名称相似不代表请求格式或素材能力相同。

生成完成后的下载显示「正在取回生成结果」。单次状态读取最多等待 45 秒，单次内容下载最多等待 5 分钟，仍受调用方更短的截止时间限制；网络暂时中断时按原任务 ID 继续查询和下载，不重新提交付费生成。创建请求保留原生成等待时间。

内置渠道的视频状态读取携带 X-Beeftv-Video-Delivery: direct；其中 Seedance 每 5 秒查询网关已保存的任务状态。Gemini、Vertex 及其他内置渠道视频保持原有默认 30 秒频率，避免在服务端实时查询模式下增加上游请求。支持该请求头的网关可在 Seedance 上游生成成功后立即返回视频直链，同时在后台保存备用文件；旧客户端继续使用网关原有的交付路线。自定义渠道和调用方指定的查询频率保持原样。

直链下载发生可恢复的网络错误、外部签名地址过期，或连续 10 秒没有收到新字节时，客户端改用同一任务的 GET /v1/videos/:id/content?delivery=backup。备用接口每次提供新鲜的下载地址；外部地址过期时重新请求该接口，不复用过期链接。备用文件尚未准备好时，按 503 / video_delivery_pending 和 Retry-After 等待原结果，不消耗传输失败的重试次数。持续收到数据的下载不会被 10 秒计时截断，仍受原有单次下载期限、文件大小和并发限制。

Seedance 专用调度与声明式视频插件共用该下载合同，包括直接结果 URL 和独立内容端点。API 凭据、渠道自定义请求头不发送给外部视频地址；重定向仍经过统一出站地址校验。网关本身拒绝凭据或用户取消时停止取回，不触发备用下载或重新生成。取回文件不读写模型生成的熔断状态，避免素材线路故障阻止已完成视频的下载。其他供应商沿用原行为。

出站连接仅尝试已通过地址校验的 DNS 结果，先尝试首选地址，250 毫秒后尝试另一地址族，再尝试其余地址。这样可以绕过不可用的 IPv6 或 IPv4 路线；不会重新解析主机名，也不会因此重发生成请求。默认允许本机回环、RFC1918 和 Tailscale/CGNAT（100.64.0.0/10）上的 HTTP/HTTPS 模型服务；链路本地（含 169.254.169.254）、未指定地址、组播，以及 URL 中的账号密码仍然拒绝。CANVAS_ALLOWED_PRIVATE_UPSTREAM_HOSTS 不能放行这些地址。需要公网隔离时设置 CANVAS_ALLOW_PRIVATE_UPSTREAMS=false，再按主机名精确放行。

外接视频协议选择

第三方服务的新视频模型需要明确选择请求协议；仅有“OpenAI 兼容”或模型名称不能确认视频接口格式。目录明确标注合同且对应插件已启用时，才可采用该协议。已有用户配置保持原样。

自定义渠道统一使用用户明确选择的请求协议，不按域名或模型名称自动更换协议。选择「视频生成 JSON · ratio / duration」后，同一格式的其他服务地址和模型也可完整发送多张参考图；顺序保持不变，未指定首尾帧的图片明确标为 reference_image。模型能力设置中的数量等限制仍生效。旧配置若误选了 newapi（Sora multipart），请在模型的高级设置中选择与服务商实际接口一致的 JSON 协议。插件未安装或停用时仍在发送前失败。

• OpenAI Videos / Sora 使用 POST /v1/videos 和 multipart，最多一张参考图。不支持的多图、参考视频、参考音频、尾帧及蒙版会在提交前报错。
• OpenAI 已于 2026-09-24 关闭官方 Sora 2 模型与 Videos API，且没有一对一的替代接口；这条协议现在只对仍转发同名 /v1/videos 合同的第三方中转有意义。用普通 OpenAI Key 直接在 api.openai.com 生成视频不保证可用。
• Google 已停止 Gemini API 的 Veo 预览模型（2026-10-22）与 Veo 3.0 / 2.0 正式模型（2026-06-30），官方建议改用 Gemini Omni Flash；gemini-veo 协议保留给仍转发同名 predictLongRunning 的中转或尚未关闭的模型。
• Runway 的 promptImage 按模型区分：gen4.5、gen4_turbo、gemini_omni_flash、grok_imagine_1_5 等模型的 position 只有 first，带尾帧会在提交前报错；veo3.1、kling2.5_turbo_pro、seedance2_5、h3_max 等支持尾帧的模型照常发送，本地只拦官方明确限制的单帧模型。创建与查询都带官方的 X-Runway-Version。
• Luma 的 keyframes.frame0.url 只接受在线图片地址：本地首帧先上传到对象存储换成在线地址，拿不到在线地址时在提交前报错（reference_media_requires_url），不会把 data URL 发进该字段。
• 「视频生成 JSON · ratio / duration」使用 POST /v1/video/generations 和 JSON，发送 images 对象数组及图片角色、整数 duration、ratio，并从查询结果 data[].url 取回视频。只有服务商文档符合该格式时才选择。
• 既有 NewAPI Video Generations 使用 seconds/aspect_ratio/image_urls，与上一项的字段不同；方舟原生、fal 和其他专用协议也须按各自文档选择。

在「设置 → 模型服务 → 管理服务 → 高级模型设置与测试 → 配置使用」选择协议，并按服务商文档设置素材与参数限制。生成测试会收费；保存配置和选择协议本身不会提交生成。HTTP 错误或超时后不会自动改用其他协议重发。

企业模型

backend/internal/providerpreset/video_contracts.json 是已核验企业视频线路的共用声明，后端模型目录、素材处理和前端配置直接读取同一份文件。声明包含匹配模型、协议、是否允许内嵌素材、是否必须使用 HTTP 参考地址，以及有明确限制时的参考素材数量和生成模式。

maxReferences 可只约束部分素材类型；未声明的类型保留原有模型能力限制，0 明确表示不支持该类型。前后端都遵循这一规则。

桌面助手的 model.catalog 对已声明的内置渠道地址应用同一份视频合同，投影真实的声音开关、时长、分辨率与参考数量。generateAudio.supported 表示可选择生成声音，default 保留已保存的默认值；支持声音不会自动把用户关闭的声音打开。带 videoCapabilitiesVersion 的渠道目录保留其明确能力配置，自定义上游地址不应用内置渠道合同。

• Seedance 2.0 / 2.5 使用既有 Seedance 请求处理和素材规格检查。内置渠道的本地参考图片、视频、音频由本机后端先交给同一企业接口签发的短期地址，再在 /v1/videos 只发送 HTTPS 链接，避免把整份文件编进 JSON。工作区已有公开访问地址时，仍上传这些本机文件，不改成工作区自己的地址。调用方已经提供的 HTTPS 或 asset:// 地址保持原样。不自动裁剪、压缩或截断。旧接口没有该上传能力时，仅在整次 JSON 仍不超过 64MiB 时沿用内嵌数据。直连方舟、自定义渠道和其他模型保持原传输方式。
• Wan 3.0 当前接入支持文生视频和单图生视频，VOD 路由只接受 HTTP 参考地址（requiresHTTPReferences）。桌面任务的本地图片复用上述内置渠道素材上传，再由官方 JSON 视频插件将地址写入 image_urls；已有 HTTP/HTTPS 引用保持原样。上传失败会在生成提交前停止，不回退为内嵌数据或 asset://。声音、时长和分辨率仍取本次配置，不因上传重写。直接前端传输仍要求在线地址，不会直接发送内嵌图片。当前接入只开放一张图片，参考视频、参考音频和多图会在提交前拒绝；这是当前接入能力，不代表模型本身永远不支持这些输入。
• 未声明的模型保留模型目录或用户明确选择的协议，不根据供应商品牌放开本地素材支持。
• 通用素材处理遵循已安装插件的 requiresPublicMediaUrls 声明。要求公网地址的线路不会把本机地址发送给上游，也不会自动公开用户文件。
• 只接受公网链接的渠道会在任务入队前检查参考素材，并指出需要替换的图片、视频或音频序号。可换用 HTTPS 素材链接，或在渠道设置中选择与服务商实际接口相符、支持本地素材的协议；不会仅凭模型名称自动切换协议。

自定义全参视频服务

服务商支持分片素材上传及全参视频接口时，在模型的高级设置中选择「全参视频」协议。模型名称本身不能证明协议兼容；请按服务商的接口说明选择。

图片、视频和音频参考先上传到所配置的 API 服务，完成后核对字节数与 SHA256，再提交视频任务。素材地址默认必须与 API 同主机。如果服务商另有素材域名，在连接的「高级设置」中填写「素材服务地址」，只填源站，不带路径、账号或查询参数。公网源站使用 HTTPS，端口为空或 443。已填写的本机、局域网或 CGNAT 源站可以是 HTTP，也可以带其他端口；回执里的地址必须与这个源站的协议、主机和端口一致，不能改指另一台局域网机器。未填写时不接受跨主机地址。此设置不会向素材源站发送 API Key。CANVAS_ALLOW_PRIVATE_UPSTREAMS=false 时，跨主机素材源站只接受公网 HTTPS 443。

任务结果若返回以 / 开头的相对地址，客户端按所配置的 API 源站解析。下载仍受外部地址校验约束；只有同源下载使用该服务的凭据。

新增模型验收

1. 核验当前线路的创建、查询和结果格式，以及每种参考素材的传输方式、数量、大小、时长和格式限制。
2. 复用已有协议插件；确有不同线协议时再增加插件。企业线路的例外能力写入共用合同，不在页面中增加模型名称判断。
3. 添加合同与请求测试，覆盖本地素材、数量边界、未知模型不继承能力、配置重载，以及插件缺失或停用。
4. 实际提交最小样例，验证任务终态、结果可读取和保存；接单成功不能替代生成成功。

新增模型仍需要协议核验与实际验收；共用流程减少重复实现，不代替供应商能力确认。