> ## 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배로 증가시키거나, 원본 해상도(1x)에서 품질 향상을 적용합니다.

## 동작 방식

비디오 업스케일링은 비디오 생성과 같은 비동기 큐 시스템을 사용합니다:

1. **큐** — `topaz-video-upscale` 모델과 함께 비디오를 `/video/queue`에 제출
2. **폴링** — 반환된 `queue_id`로 `/video/retrieve`를 호출해 상태가 `completed`가 될 때까지 확인
3. **완료** — `/video/complete`를 호출해 마무리하고 출력 URL을 받음

서버는 업로드된 파일에서 input 비디오의 길이, 프레임 속도, 크기를 자동으로 감지합니다. 이 값들을 제공할 필요가 없습니다 — 과금은 실제 비디오 메타데이터에서 계산됩니다.

## 업스케일 배수

| `upscale_factor` | Output resolution | Use case                       |
| ---------------- | ----------------- | ------------------------------ |
| `1`              | input과 동일         | 품질 향상만(잡음 제거, 샤프닝)             |
| `2`(기본)          | input 크기의 2배      | 표준 업스케일 — 720p input은 1440p 출력 |
| `4`              | input 크기의 4배      | 최대 업스케일 — 480p input은 1920p 출력 |

<Note>
  `upscale_factor` 파라미터는 업스케일 모델에서 `resolution`을 대체합니다. `resolution`을 전달하면 에러를 반환합니다. 이는 출력 해상도가 input 비디오의 크기에 따라 다르기 때문입니다 — 720p 비디오의 `2x` 업스케일과 480p 비디오의 `2x` 업스케일은 다른 결과를 만듭니다.
</Note>

## 지원 input 포맷

* **포맷**: MP4, MOV, WebM
* **Input 방식**: 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로 마무리

결과를 retrieve한 후 `/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 파라미터

| Field            | Type   | Required | Description                                       |
| ---------------- | ------ | -------- | ------------------------------------------------- |
| `model`          | string | **예**    | `topaz-video-upscale`여야 함                         |
| `video_url`      | string | **예**    | Input 비디오 URL 또는 data URL. 지원 포맷: MP4, MOV, WebM. |
| `upscale_factor` | number | 아니오      | `1`, `2`(기본), `4`. 업스케일 배수 제어.                    |

### 업스케일 모델에서 사용하지 않는 파라미터

다음 파라미터는 `topaz-video-upscale`에서 **허용되지 않으며** 제공하면 에러를 반환합니다:

| Field        | Reason                                           |
| ------------ | ------------------------------------------------ |
| `resolution` | 대신 `upscale_factor` 사용. 출력 해상도는 input 크기에 따라 다름. |
| `prompt`     | 업스케일링은 텍스트 prompt를 사용하지 않음. 빈 문자열이 자동 설정됨.       |

`duration` 파라미터도 무시됩니다 — 서버는 과금 정확성을 위해 비디오 파일에서 직접 길이를 감지합니다.

***

## 가격

가격은 **길이**, **출력 해상도 등급**, **프레임 속도**를 기반으로 합니다. 출력 해상도 등급은 input 비디오 높이에 업스케일 배수를 곱한 값으로 결정됩니다.

### 출력 해상도 등급

| Tier  | Output height | Per-second rate |
| ----- | ------------- | --------------- |
| 720p  | ≤ 720px       | \~\$0.013       |
| 1080p | 721–1080px    | \~\$0.025       |
| 4K    | > 1080px      | \~\$0.10        |

<Note>
  48fps를 초과하는 프레임 속도의 비디오는 초당 요율의 2배입니다.
</Note>

### 가격 예시

| Input        | Upscale factor | Output          | Duration | Estimated cost |
| ------------ | -------------- | --------------- | -------- | -------------- |
| 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
  }'
```

Quote endpoint는 출력 해상도 등급을 추정할 수 있도록 `input_height`를 받습니다. 선택 사항입니다 — 생략하면 견적이 보수적인 추정을 가정합니다.

***

## 문제 해결

| Problem                                      | Likely cause             | Fix                                                               |
| -------------------------------------------- | ------------------------ | ----------------------------------------------------------------- |
| `"Use upscale_factor instead of resolution"` | 요청에 `resolution`을 전달     | `resolution`을 제거하고 `upscale_factor` 사용                            |
| 예상보다 높은 비용                                   | Input 비디오가 고해상도 또는 고 FPS | quote endpoint로 input 크기 확인. 720p+ input에 2x 업스케일은 4K 가격 등급에 들어감. |
| 작업에 오랜 시간 소요                                 | 큰 또는 긴 비디오               | 업스케일링은 컴퓨트 집약적. 긴 비디오와 더 높은 업스케일 배수는 비례적으로 더 오래 걸림.               |
| `"Insufficient balance"`                     | 계정 크레딧 부족                | [venice.ai/settings/api](https://venice.ai/settings/api)에서 크레딧 추가 |