Spaces:
Running on Zero
Running on Zero
| 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`。 | |
| 创建任务： | |
| ```bash | |
| 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`： | |
| ```json | |
| {"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"}`。完成后返回： | |
| ```json | |
| {"video_url":"https://.../api/jobs/.../video?token=...","used_seed":42} | |
| ``` | |
| `video_url` 自带短期随机凭证，不再需要 API key。它支持 `GET`、`HEAD` 和单区间 `Range`： | |
| ```bash | |
| 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 身份。 | |