# Wan 3.0 Prime

使用此模型提交视频生成任务，再通过返回的任务 ID 查询结果。

模型 ID `wan-3-0-pro`

## 快速开始

创建 [API 密钥](/me?section=api-keys)并设置 `I2V_API_KEY`。每个新任务设置一个 `IDEMPOTENCY_KEY`，重试同一次提交时复用原幂等键和请求体。

### 提交任务

`POST https://api.i2v.ai/api/v1/jobs/createTask`

```bash
curl "https://api.i2v.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "wan-3-0-pro",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "duration": 5,
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}'
```

HTTP 200 表示任务已受理。保存返回的 `taskId`。

```json
{"taskId":"YOUR_TASK_ID"}
```

### 查询结果

```bash
curl "https://api.i2v.ai/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

将 `YOUR_TASK_ID` 替换为返回的任务 ID。状态为 `waiting` 或 `generating` 时退避轮询。`success` 时读取 `output[].url`，`fail` 时检查 `error`。

## 请求参数

模型输入放在 `inputs` 对象中。素材 URL 需要可公开访问。必需素材及参数组合取决于具体生成模式。

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `inputs.prompt` | string | 否 | — | 镜头描述；参考素材已完整定义请求时可为空。 上限 20000 字符. |
| `inputs.resolution` | string | 否 | 1080p | 输出分辨率。 可选值 `480p`, `720p`, `1080p`. |
| `inputs.aspectRatio` | string | 否 | 16:9 | 输出宽高比。 可选值 `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `adaptive`. |
| `inputs.duration` | number | 否 | 5 | 视频时长，单位为秒。 可选值 `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`. |
| `inputs.urls` | string[] | 否 | — | 关键帧图片地址，前两项分别为首帧和尾帧。 上限 2 个 URL. |
| `inputs.referenceImageUrls` | string[] | 否 | — | 最多 10 张参考图；不能与首尾帧同时使用。 上限 10 个 URL. |
| `inputs.referenceVideoUrls` | string[] | 否 | — | 最多 5 段参考视频，用于引导运动与质感。 上限 5 个 URL. |
| `inputs.referenceAudioUrls` | string[] | 否 | — | 最多 5 段参考音频，用于引导声音。 上限 5 个 URL. |
| `inputs.videoUrl` | string | 否 | — | 视频转视频模式使用的源视频地址。 |
| `inputs.generateAudio` | boolean | 否 | — | 是否同时生成视频声音。 |

### 请求顶层字段

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | `wan-3-0-pro` | 公开模型 ID，使用本页显示的准确值。 |
| `maxCostUsd` | string | 否 | — | 可选的美元费用上限，以最多八位小数的字符串传入。报价超出上限时会在生成前返回 HTTP 409。 |
| `callBackUrl` | string | 否 | — | 可选的公共 HTTPS 回调地址。签名配置见[任务回调](/docs/webhooks)。 |
| `expectedRevision` | number | 否 | — | 可选的模型发布版本，用于乐观并发校验。 |

## 响应结构

以下为成功响应示例，结果链接为占位值。实际美元费用由提交参数决定。任务待完成时，部分字段可能为 null。

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "wan-3-0-pro",
  "status": "success",
  "billing": null,
  "output": [
    {
      "url": "https://example.com/result.mp4"
    }
  ],
  "error": null,
  "createTime": 1760000000000,
  "completeTime": 1760000060000
}
```

| 状态 | 含义 |
| --- | --- |
| `waiting` | 排队中 |
| `generating` | 生成中 |
| `success` | 已完成，读取 output[].url。 |
| `fail` | 生成失败，查看 error.code 和 error.message。 |

## 代码示例

### Node.js

```javascript
const baseUrl = "https://api.i2v.ai";
if (!process.env.I2V_API_KEY || !process.env.IDEMPOTENCY_KEY) {
  throw new Error('Set I2V_API_KEY and a stable IDEMPOTENCY_KEY before submitting.');
}
const headers = {
  Authorization: `Bearer ${process.env.I2V_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': process.env.IDEMPOTENCY_KEY,
};
const response = await fetch(baseUrl + '/api/v1/jobs/createTask', {
  method: 'POST', headers,
  body: JSON.stringify({
  "model": "wan-3-0-pro",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "duration": 5,
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}),
});
const created = await response.json();
if (!response.ok) throw new Error(JSON.stringify(created));

const deadline = Date.now() + 30 * 60_000;
let delayMs = 2_000;
let output;
while (Date.now() < deadline) {
  const result = await fetch(baseUrl + '/api/v1/jobs/recordInfo?taskId=' + encodeURIComponent(created.taskId), { headers });
  const task = await result.json();
  if (!result.ok || task.status === 'fail') throw new Error(JSON.stringify(task));
  if (task.status === 'success') {
    output = task.output;
    break;
  }
  await new Promise(resolve => setTimeout(resolve, delayMs));
  delayMs = Math.min(delayMs * 1.5, 30_000);
}
if (!output) throw new Error('Polling timed out. Resume with taskId ' + created.taskId);
console.log(output.map(item => item.url));
```

### Python

```python
import json
import os
import time
import urllib.parse
import urllib.request

base_url = "https://api.i2v.ai"
headers = {
    'Authorization': 'Bearer ' + os.environ['I2V_API_KEY'],
    'Content-Type': 'application/json',
    'Idempotency-Key': os.environ['IDEMPOTENCY_KEY'],
}
payload = json.loads("{\"model\":\"wan-3-0-pro\",\"inputs\":{\"prompt\":\"A calm lake at sunrise\",\"duration\":5,\"resolution\":\"1080p\",\"aspectRatio\":\"16:9\"}}")
request = urllib.request.Request(
    base_url + '/api/v1/jobs/createTask',
    data=json.dumps(payload).encode(), headers=headers, method='POST',
)
with urllib.request.urlopen(request, timeout=60) as response:
    created = json.load(response)

deadline = time.monotonic() + 30 * 60
delay = 2
while time.monotonic() < deadline:
    query = urllib.parse.urlencode({'taskId': created['taskId']})
    request = urllib.request.Request(base_url + '/api/v1/jobs/recordInfo?' + query, headers=headers)
    with urllib.request.urlopen(request, timeout=60) as response:
        task = json.load(response)
    if task['status'] == 'fail':
        raise RuntimeError(task['error'])
    if task['status'] == 'success':
        print([item['url'] for item in task['output']])
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 30)
else:
    raise TimeoutError('Polling timed out. Resume with taskId ' + created['taskId'])
```

### 2K delivery with a reference image

```json
{
  "model": "wan-3-0-pro",
  "inputs": {
    "prompt": "A slow aerial push over a coastal town at golden hour",
    "referenceImageUrls": [
      "https://example.com/location.png"
    ],
    "duration": 5,
    "resolution": "2k",
    "generateAudio": false
  }
}
```

## 美元价格

以下价格来自已发布模型目录，请核对对应配置和计费单位。

| 模式 | 分辨率 | 时长 | USD | 计费单位 |
| --- | --- | --- | --- | --- |
| standard | 480p | — | 0.05440000 USD | second |
| standard | 720p | — | 0.11200000 USD | second |
| standard | 1080p | — | 0.22400000 USD | second |

## 错误与重试

常见提交错误包括 `400 invalid_params`、`401 unauthorized`、`402 insufficient_balance`、`409 conflict`、`429 concurrency_limit` / `rate_limit`。恢复流程见[错误与重试](/docs/errors)，签名完成通知见[任务回调](/docs/webhooks)。