> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 비디오 업스케일링

> Venice API에서 Topaz Video Upscale 모델로 비디오 해상도를 높이는 비동기 /video/queue 워크플로 가이드입니다.

비디오 업스케일링을 사용하면 기존 비디오를 더 높은 해상도로 향상시키면서 시각 품질을 개선할 수 있습니다. **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={null}
  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={null}
  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={null}
  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={null}
{
  "model": "topaz-video-upscale",
  "queue_id": "abc123-def456-..."
}
```

### 완료 폴링

<CodeGroup>
  ```bash cURL theme={null}
  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={null}
  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={null}
  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={null}
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={null}
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",
    "video_url": "https://example.com/input.mp4"
  }'
```

업스케일 모델의 견적에는 `video_url`이 **필수**입니다 — quote endpoint가 파일을 가져와 바이트에서 duration, FPS, 높이를 감지하므로 직접 제공할 필요가 없습니다. 생략하면 `400`과 함께 \*"video\_url is required for quotes on this model"\*이 반환됩니다.

<Warning>
  현재 quote와 queue endpoint는 업스케일 배수의 이름을 다르게 사용합니다: `/video/queue`는 `upscale_factor`(`1`, `2`, `4`)를 받고, `/video/quote`는 `resolution`(`"2x"` 또는 `"4x"`)에서 배수를 읽습니다. quote endpoint에 `upscale_factor`를 보내면 아무 효과가 없습니다 — 기본값 `"2x"`로 대체되어 4x 작업일 수도 있는 것에 대해 2x 가격을 반환합니다. 4x 업스케일의 견적을 낼 때는 `resolution: "4x"`를 전달하세요.
</Warning>

***

## 문제 해결

| 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?utm_source=venice-api-documentation)에서 크레딧 추가 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.