메인 콘텐츠로 건너뛰기
비디오 업스케일링을 사용하면 기존 비디오를 더 높은 해상도로 향상시키면서 시각 품질을 개선할 수 있습니다. Topaz Video Upscale 모델은 AI 기반 업스케일링으로 해상도를 2배 또는 4배로 증가시키거나, 원본 해상도(1x)에서 품질 향상을 적용합니다.

동작 방식

비디오 업스케일링은 비디오 생성과 같은 비동기 큐 시스템을 사용합니다:
  1. 큐 — topaz-video-upscale 모델과 함께 비디오를 /video/queue에 제출
  2. 폴링 — model과 반환된 queue_id로 /video/retrieve를 호출합니다. 작업이 실행되는 동안에는 "status": "PROCESSING"이 담긴 JSON을 반환합니다. 작업이 끝나면 응답 본문이 업스케일된 MP4(Content-Type: video/mp4)이므로 파일로 저장하세요. 출력 URL은 없습니다.
  3. 정리(선택) — 파일을 저장한 후 /video/complete를 호출해 저장된 출력을 삭제합니다
서버는 업로드된 파일에서 input 비디오의 길이, 프레임 속도, 크기를 자동으로 감지합니다. 이 값들을 제공할 필요가 없습니다 — 과금은 실제 비디오 메타데이터에서 계산됩니다.

업스케일 배수

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

지원 input 포맷

  • 포맷: MP4, MOV, WebM
  • Input 방식: HTTPS URL 또는 data:video/...;base64,... data URL
  • 최대 길이: 300초(5분)

API 사용법

업스케일 작업 큐 등록

응답에는 작업을 추적할 queue_id가 포함됩니다:

폴링 및 결과 저장

완성된 업스케일 결과는 JSON 필드가 아니라 응답 본문 자체이므로, 파싱하기 전에 Content-Type을 확인하세요. cURL 예시는 각 응답의 content type을 출력합니다. video/mp4가 출력될 때까지 반복하면, 그 시점에 upscaled.mp4에 비디오가 저장되어 있습니다. 큐 응답에 download_url이 포함되어 있었다면, retrieve는 대신 "status": "COMPLETED"가 담긴 JSON을 반환하며, 해당 URL에서 파일을 다운로드합니다. Private 다운로드 링크를 참고하세요.

정리(선택)

MP4를 저장한 후 /video/complete를 호출해 저장된 출력을 삭제할 수 있습니다. 이 호출은 비디오나 URL을 반환하지 않습니다.

API 파라미터

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

다음 파라미터는 topaz-video-upscale에서 허용되지 않으며 제공하면 에러를 반환합니다: duration 파라미터도 무시됩니다 — 서버는 과금 정확성을 위해 비디오 파일에서 직접 길이를 감지합니다.

가격

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

출력 해상도 등급

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

가격 예시

작업 제출 전 정확한 가격을 받으려면 Video Quote API를 사용하세요.

견적 받기

업스케일 모델의 견적에는 video_url이 필수입니다 — quote endpoint가 파일을 가져와 바이트에서 duration, FPS, 높이를 감지하므로 직접 제공할 필요가 없습니다. 생략하면 400과 함께 *“video_url is required for quotes on this model”*이 반환됩니다. 업스케일 모델의 견적에는 API 키가 필요합니다. API 키 없이 요청하면 403이 반환됩니다. 견적이 작업과 일치하도록 /video/queue에 보낼 것과 동일한 upscale_factor(1, 2, 4)를 /video/quote에 전달하세요. quote는 업스케일 모델에 대해 더 이상 사용되지 않는 별칭으로 resolution("2x" 또는 "4x")도 받습니다. 둘 다 보내면 upscale_factor가 우선합니다.

문제 해결