通用视频生成

WisGate 提供 /v1/videos 创建和查询视频任务，使用接近 OpenAI Videos 的请求与任务结构。生成是异步操作：创建成功只说明收到任务，需要继续查询直到完成。

本页示例使用 sora-2，前提是当前 API Key 有对应可用渠道。其他视频模型必须使用其支持的时长、尺寸和素材类型。文本模型 deepseek-v4-flash 不用于视频生成。

接口清单

方法	路径	本平台行为
POST	/v1/videos	创建视频任务，解析 JSON 或 multipart 表单
GET	/v1/videos/{id}	查询当前用户任务快照
GET	/v1/videos/{id}/content	代理上游视频二进制内容，有渠道限制，见下载说明

当前没有在该模块注册 GET /v1/videos 列表、DELETE /v1/videos/{id} 或 remix/edit/extension/角色管理端点。OpenAI 官方 Videos 的能力范围大于本平台当前公开实现。OpenAI Videos 参考

平台还有 /v1/video/generations 历史统一入口，其响应契约不能与本页混用。Seedance 推荐使用独立的 Seedance 生视频协议。

创建文生视频任务

curl --fail-with-body https://api.wisgate.cn/v1/videos \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "sora-2",
    "prompt": "清晨的海岸，海浪轻拍沙滩，镜头缓慢平移，无字幕。",
    "size": "1280x720",
    "seconds": "8"
  }'

这是参数组合示例，需当前渠道支持 sora-2、8 秒和该尺寸。不要由单个示例推导出所有模型的枚举值。

也可以使用 multipart。特别是直接上传参考图时使用表单：

curl --fail-with-body https://api.wisgate.cn/v1/videos \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -F 'model=sora-2' \
  -F 'prompt=保持参考图主体，生成自然流畅的产品展示镜头。' \
  -F 'size=1280x720' \
  -F 'seconds=8' \
  -F 'input_reference=@reference.png;type=image/png'

不要手工设置 multipart 的 Content-Type，curl 会生成 boundary。将 reference.png 替换为本地图片文件。模型可能要求参考图尺寸、格式与输出参数匹配。

参数表

字段	类型	要求与限制
model	string	必填，WisGate 模型名
prompt	string	文生视频必填；部分渠道允许仅参考素材，但不是通用保证
seconds	string / number	时长，推荐 OpenAI 风格字符串；允许值由模型决定
size	string	像素尺寸，例如 1280x720；不要填写 Seedance 的 720p 代替
input_reference	multipart file	上传参考图片；当前 Sora 路径保留文件，其他渠道有不同限制
duration	number	平台兼容时长别名；同层同时提供时解析优先采用正数 seconds
resolution、ratio	string	平台扩展，只有对应供应商转换器支持才生效
image / images	string / string[]	平台 URL 图片扩展，依赖目标渠道，不是所有 OpenAI Videos 模型的通用字段
content	array	平台多媒体扩展，依赖转换器；Seedance 复杂素材建议使用专用协议
n / video_count、frames、mode、metadata	各自模型类型	兼容扩展，不建议通用最小示例携带

本地 JSON 解析器还读取 options 中的尺寸/时长参数，优先级与顶层不同。建议只用一处定义参数，避免混合新旧格式产生歧义。未知 JSON 和表单字段在 Sora 路径可保留，但不等于所有上游支持，也不等于其他供应商路径同样透传。

平台不会静默把无法转换的音频/视频/上传文件都降级为纯文本。新分配路径对不匹配素材会拒绝请求，例如当前 Vertex 视频转换不支持图片参考、可灵转换仅支持一张参考图。参数可解析与供应商支持需分开判断。

创建响应与任务 ID

创建响应的字段数量随渠道不同，以下是结构示例：

{
  "id": "video_example",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1791504000
}

必须保存实际返回的 id，不要自行拼装上游任务号。平台可能使用公开任务 ID 映射。返回 2xx 与 queued 均不表示视频已经成功生成。

查询结果

curl --fail-with-body https://api.wisgate.cn/v1/videos/video_example \
  -H "Authorization: Bearer $WISGATE_API_KEY"

status	意义	下一步
queued	已提交或排队	稍后继续查询
in_progress	生成中	继续查询
completed	完成	下载结果
failed	失败	读取 error，停止轮询
unknown / 未识别值	平台兜底或上游扩展	保留原响应，按超时策略处理，不当作成功

部分供应商查询结果保留原始字段，不能要求所有渠道完全一致。常见返回字段：

字段	含义
id、object、model	任务标识、对象类型、模型
status、progress	状态与进度；progress 可能粗粒度更新
created_at、completed_at、expires_at	Unix 秒时间戳；后两者可能缺失
seconds、size	输出参数，可能由上游返回
error.code、error.message	任务失败信息
meta_data.url	部分非 Sora 渠道提供的结果 URL，注意字段拼写

普通查询可能读本地快照，状态不一定立即随上游变化。建议每数秒查询一次，按业务设置总超时；这是客户端建议，不是平台固定 SLA。

Python 有界轮询示例（安装 requests，替换任务 ID）：

import os
import time
import requests

task_id = "video_example"
headers = {"Authorization": "Bearer " + os.environ["WISGATE_API_KEY"]}
deadline = time.monotonic() + 900
while time.monotonic() < deadline:
    response = requests.get(
        f"https://api.wisgate.cn/v1/videos/{task_id}", headers=headers, timeout=30
    )
    response.raise_for_status()
    task = response.json()
    if task.get("status") == "completed":
        print(task)
        break
    if task.get("status") == "failed":
        raise RuntimeError(task.get("error", task))
    time.sleep(5)
else:
    raise TimeoutError("本次轮询超时；保存任务 ID，稍后继续查询，不要重复创建任务。")

下载

对于提供 OpenAI 兼容下载端点的上游：

curl --fail-with-body --location \
  https://api.wisgate.cn/v1/videos/video_example/content \
  --output result.mp4

该平台路由当前是匿名内容代理，不继承创建/查询使用的 API Key 鉴权，并设置公开缓存。因此内容链接及任务 ID 应按可访问资源管理。这里如实描述当前实现，不应写成“所有下载都受同一 Key 保护”。

下载实现会访问原渠道 /v1/videos/{provider_task_id}/content，不会自动把所有供应商的 URL 结果转换成同一个下载服务。若渠道只提供 meta_data.url 等结果地址，应直接下载该 URL。当前未实现 OpenAI 的 thumbnail/spritesheet variant 转发，不能承诺这些格式。

失败下载可能返回 JSON 错误，检查 HTTP 状态后再把文件当作视频。结果地址有时效性，成功后及时转存。

SDK 接入

如所用 OpenAI Python SDK 提供 Videos 资源，可按以下方式调用兼容入口；渠道差异仍以原始 HTTP 返回为准：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["WISGATE_API_KEY"], base_url="https://api.wisgate.cn/v1")
task = client.videos.create(
    model="sora-2", prompt="清晨海岸，镜头缓慢平移。", seconds="8", size="1280x720"
)
print(task.id)
print(client.videos.retrieve(task.id))

不要因为 SDK 暴露了 list/delete/remix 等方法，就认为网关对应接口已经实现。

失败与重复提交

生成失败应查看查询响应中的 error；请求阶段错误可能是 OpenAI 风格 error，也可能是平台 {code,message,data}。客户端应先判断 HTTP 状态，再解析实际错误体。

提交超时并不能证明上游没有创建任务。保存已取得的任务 ID，避免重发相同请求造成重复生成。当前没有通用的 Idempotency-Key 幂等约定。429 或暂时性 5xx 可采用有界退避；参数错误先修改请求。