---
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 身份。