README.md

metadata

title: Wan2.2 14B Fast Preview [NEW]
emoji: 🏆
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false

Wan 2.2 I2V 14B Lightning · ZeroGPU

本 Space 保留 Gradio UI、MCP、/generate_video 与 /extract_frame，并额外提供一个不依赖 Gradio SSE 的异步视频任务 API。任务状态和幂等索引保存在当前进程内，Space 重启后不会保留；完成结果默认保存 1800 秒。

Space 配置

必需 Secret：

• HF_TOKEN：仅用于读取模型或私有 LoRA，不会替代调用方的 Hugging Face 身份。
• JOB_API_KEY：至少 32 字符的随机共享密钥，仅通过 X-API-Key 传入，禁止提交到仓库。

平台内置 Variable：

• SPACE_HOST：由 Hugging Face 自动注入，代码用它生成公开 URL；这是保留变量，不能在 Space Settings 中手工创建同名 Variable。

必需 Variable：

• JOB_IMAGE_ALLOWED_HOSTS：允许抓取首图和尾图的精确主机名，以逗号分隔，不支持通配符、协议、端口或路径。

可选 Variable：

• JOB_RESULT_TTL_SECONDS：终态结果保留秒数，默认 1800。
• JOB_POLL_AFTER_SECONDS：建议轮询间隔，默认 2。
• JOB_IMAGE_FETCH_TIMEOUT_SECONDS：单图连接与总抓取期限，默认且最大 15。
• JOB_IMAGE_MAX_BYTES：单图字节上限，默认且最大 20971520（20 MiB）。
• JOB_IMAGE_MAX_PIXELS：单图像素上限，默认且最大 40000000。

修改 Secret 或 Variable 会触发 Space 重启。

自定义视频任务 API

所有任务管理请求都需要 X-API-Key。Idempotency-Key 可省略，正式调用方应提供不超过 200 字符的稳定唯一值。相同键与相同请求体只会生成一次；相同键配合不同请求体返回 409。

创建任务：

curl -i -X POST "https://idlecloudx-i2v-1.hf.space/api/jobs" \
  -H "X-API-Key: your-shared-random-key" \
  -H "Idempotency-Key: caller-generated-unique-value" \
  -H "Content-Type: application/json" \
  --data '{
    "input_image_url": "https://allowed.example/input.png",
    "last_image_url": null,
    "prompt": "make this image come alive, cinematic motion, smooth animation",
    "steps": 6,
    "negative_prompt": "",
    "duration_seconds": 3.5,
    "guidance_scale": 1,
    "guidance_scale_2": 1,
    "seed": 42,
    "randomize_seed": false,
    "quality": 6,
    "scheduler": "UniPCMultistep",
    "flow_shift": 3.0,
    "frame_multiplier": 16,
    "safe_mode": true,
    "lora_groups": [],
    "gpu_duration_seconds": 59
  }'

input_image_url 必须是白名单精确主机上的 HTTPS URL；last_image_url 可空。抓取禁止重定向、用户信息、非默认端口和非公网解析地址，不会向图片主机转发 Authorization、Cookie、API key 或 ZeroGPU 请求头。每张图片仅接受实际 PNG/JPEG/WebP。lora_groups 中每一项都必须与当前 UI 下拉框显示名称完全一致。

字段边界：

字段	默认值	边界
prompt	当前 UI 默认文案	非空，最长 5000
negative_prompt	当前 UI 默认文案	最长 5000，可空
steps	6	1–30
duration_seconds	3.5	0.5–20.1
guidance_scale, guidance_scale_2	1	0–10
seed	42	0–2147483647
randomize_seed	true	布尔值
quality	6	1–10
scheduler	UniPCMultistep	UI 当前 7 个调度器之一
flow_shift	3.0	0.5–15
frame_multiplier	16	仅 16/32/64/128
safe_mode	true	布尔值
gpu_duration_seconds	59	整数 1–59

gpu_duration_seconds 只控制自定义任务向 ZeroGPU 申请的最长 GPU 时间，不改变生成参数，也不在 Space 内预估任务能否在该时间内完成。参数组合超过申请时长时由 Hugging Face 终止执行，并按普通生成失败返回脱敏的 GENERATION_FAILED。现有 UI、MCP 与 Gradio /generate_video 不接收此字段，继续使用原有动态时长估算。

成功创建返回 202，并同时设置 Location 与 Cache-Control: no-store：

{"job_id":"...","status_url":"https://.../api/jobs/...","poll_after_seconds":2}

使用同一个 API key 轮询 GET /api/jobs/{job_id}。排队或运行中返回 202、Retry-After 和 {"status":"queued"} / {"status":"running"}。完成后返回：

{"video_url":"https://.../api/jobs/.../video?token=...","used_seed":42}

video_url 自带短期随机凭证，不再需要 API key。它支持 GET、HEAD 和单区间 Range：

curl -I "https://.../api/jobs/.../video?token=..."
curl -H "Range: bytes=0-1023" "https://.../api/jobs/.../video?token=..." -o first-kib.bin

视频返回 video/mp4，有效单区间为 206；多区间或不可满足范围为 416。响应允许跨域播放，缓存策略为 private, max-age=300。

身份、配额与并发

• 不带 Authorization 时，Hugging Face 将请求计入匿名共享 ZeroGPU 配额。
• 带 Authorization: Bearer hf_<调用方令牌> 时，由 Hugging Face 将生成计入调用方自己的 ZeroGPU 配额；应用仅保留代理注入的短效身份信息到任务启动，不保存或转发 Bearer 令牌。
• 内部模型下载使用的 HF_TOKEN 永远不会充当调用方身份。
• UI 和自定义 API 共用一个非阻塞推理槽位。已有任务运行时，新自定义提交立即返回 503 与 Retry-After: 5，不会在 Space 内排队。

错误约定

• 400：URL、图片内容或 Idempotency-Key 不合法。
• 401：API key 或视频下载 token 缺失/错误。
• 404：任务不存在或结果 TTL 已过期。
• 409：幂等键冲突，或视频结果尚未就绪。
• 410：任务元数据仍在但 MP4 已丢失。
• 422：JSON Schema 校验失败，包括未知字段。
• 500：生成失败；仅返回脱敏的 GENERATION_FAILED。
• 502 / 504：图片源临时故障或抓取超时。
• 503：推理槽位繁忙，或 Hugging Face 未提供 ZeroGPU 身份。