> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 视频放大

> 在 Venice API 上使用 Topaz Video Upscale 模型增强视频分辨率和质量 —— 提交源片段、选择放大倍数并获取结果。

视频放大让您可以将现有视频提升至更高分辨率，同时改善视觉质量。**Topaz Video Upscale** 模型使用 AI 驱动的放大技术将分辨率提升 2 倍或 4 倍，或在原分辨率（1 倍）上进行质量增强。

## 工作原理

视频放大使用与视频生成相同的异步队列系统：

1. **排队** —— 使用 `topaz-video-upscale` 模型将视频提交至 `/video/queue`
2. **轮询** —— 使用返回的 `queue_id` 调用 `/video/retrieve`，直到状态为 `completed`
3. **完成** —— 调用 `/video/complete` 进行收尾并获取输出 URL

服务器会自动从上传的文件中检测输入视频的时长、帧率和尺寸。您无需提供这些值 —— 计费根据实际视频元数据计算。

## 放大倍数

| `upscale_factor` | 输出分辨率     | 用例                         |
| ---------------- | --------- | -------------------------- |
| `1`              | 与输入相同     | 仅质量增强（降噪、锐化）               |
| `2`（默认）          | 输入尺寸的 2 倍 | 标准放大 —— 720p 输入变为 1440p 输出 |
| `4`              | 输入尺寸的 4 倍 | 最大放大 —— 480p 输入变为 1920p 输出 |

<Note>
  对于放大模型，`upscale_factor` 参数取代了 `resolution`。传入 `resolution` 将返回错误。这是因为输出分辨率取决于输入视频的尺寸 —— 对 720p 视频进行 `2x` 放大与对 480p 视频进行 `2x` 放大会产生不同的结果。
</Note>

## 支持的输入格式

* **格式**：MP4、MOV、WebM
* **输入方式**：HTTPS URL 或 `data:video/...;base64,...` data URL
* **最长时长**：300 秒（5 分钟）

## API 使用

### 排队一个放大作业

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "topaz-video-upscale",
      "video_url": "https://example.com/input-video.mp4",
      "upscale_factor": 2
    }'
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      "https://api.venice.ai/api/v1/video/queue",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "topaz-video-upscale",
          "video_url": "https://example.com/input-video.mp4",
          "upscale_factor": 2,
      },
  )

  data = response.json()
  queue_id = data["queue_id"]
  print(f"Queued: {queue_id}")
  ```

  ```javascript Node.js theme={"system"}
  const response = await fetch("https://api.venice.ai/api/v1/video/queue", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "topaz-video-upscale",
      video_url: "https://example.com/input-video.mp4",
      upscale_factor: 2,
    }),
  });

  const { queue_id } = await response.json();
  console.log(`Queued: ${queue_id}`);
  ```
</CodeGroup>

响应包含用于跟踪作业的 `queue_id`：

```json theme={"system"}
{
  "model": "topaz-video-upscale",
  "queue_id": "abc123-def456-..."
}
```

### 轮询完成状态

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/retrieve \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"queue_id": "abc123-def456-..."}'
  ```

  ```python Python theme={"system"}
  import time

  while True:
      result = requests.post(
          "https://api.venice.ai/api/v1/video/retrieve",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          json={"queue_id": queue_id},
      )
      data = result.json()

      if data.get("status") == "completed":
          print(f"Video URL: {data['url']}")
          break

      time.sleep(5)
  ```

  ```javascript Node.js theme={"system"}
  const poll = async (queueId) => {
    while (true) {
      const res = await fetch("https://api.venice.ai/api/v1/video/retrieve", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ queue_id: queueId }),
      });
      const data = await res.json();

      if (data.status === "completed") {
        console.log(`Video URL: ${data.url}`);
        return data;
      }

      await new Promise((r) => setTimeout(r, 5000));
    }
  };

  await poll(queue_id);
  ```
</CodeGroup>

### 通过 complete 完成收尾

检索到结果后，调用 `/video/complete` 完成收尾：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue_id": "abc123-def456-..."}'
```

***

## API 参数

| 字段               | 类型     | 必填    | 说明                                      |
| ---------------- | ------ | ----- | --------------------------------------- |
| `model`          | string | **是** | 必须为 `topaz-video-upscale`               |
| `video_url`      | string | **是** | 输入视频 URL 或 data URL。支持的格式：MP4、MOV、WebM。 |
| `upscale_factor` | number | 否     | `1`、`2`（默认）或 `4`。控制放大倍数。                |

### 放大模型不使用的参数

以下参数对 `topaz-video-upscale` **不接受**，如果提供将返回错误：

| 字段           | 原因                                |
| ------------ | --------------------------------- |
| `resolution` | 改用 `upscale_factor`。输出分辨率取决于输入尺寸。 |
| `prompt`     | 放大不使用文本 prompt。会自动设置为空字符串。        |

`duration` 参数也会被忽略 —— 服务器直接从视频文件检测时长以确保计费准确。

***

## 定价

定价基于**时长**、**输出分辨率等级**和**帧率**。输出分辨率等级由输入视频的高度乘以放大倍数决定。

### 输出分辨率等级

| 等级    | 输出高度       | 每秒费率      |
| ----- | ---------- | --------- |
| 720p  | ≤ 720px    | \~\$0.013 |
| 1080p | 721–1080px | \~\$0.025 |
| 4K    | > 1080px   | \~\$0.10  |

<Note>
  帧率超过 48fps 的视频费用为每秒费率的 2 倍。
</Note>

### 定价示例

| 输入           | 放大倍数 | 输出             | 时长  | 预估费用     |
| ------------ | ---- | -------------- | --- | -------- |
| 480p, 30fps  | 2x   | 960p（1080p 等级） | 10s | \~\$0.25 |
| 720p, 30fps  | 2x   | 1440p（4K 等级）   | 10s | \~\$1.00 |
| 1080p, 30fps | 2x   | 2160p（4K 等级）   | 30s | \~\$3.00 |
| 360p, 24fps  | 4x   | 1440p（4K 等级）   | 10s | \~\$1.00 |
| 480p, 60fps  | 2x   | 960p（1080p 等级） | 10s | \~\$0.50 |

使用 [Video Quote API](/api-reference/endpoint/video/quote) 在提交作业前获得准确定价。

### 获取报价

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/quote \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-video-upscale",
    "duration": "10",
    "input_height": 720
  }'
```

报价端点接受 `input_height`，以便估算输出分辨率等级。这是可选的 —— 若省略，报价将采用保守估算。

***

## 故障排查

| 问题                                           | 可能原因                | 解决方法                                                          |
| -------------------------------------------- | ------------------- | ------------------------------------------------------------- |
| `"Use upscale_factor instead of resolution"` | 请求中传入了 `resolution` | 移除 `resolution`，改用 `upscale_factor`                           |
| 费用高于预期                                       | 输入视频分辨率或 FPS 较高     | 使用 quote 端点检查输入尺寸。720p+ 输入加 2x 放大会落入 4K 定价等级。                 |
| 作业耗时较长                                       | 视频较大或较长             | 放大是计算密集型操作。视频越长、放大倍数越高，耗时按比例增加。                               |
| `"Insufficient balance"`                     | 账户余额不足              | 在 [venice.ai/settings/api](https://venice.ai/settings/api) 充值 |