튜토리얼
HiAPI API로 topaz-upscale/video 사용하는 방법: curl 및 Python 예제
이 페이지에서
topaz-upscale/video의 기능과 적용 시나리오
topaz-upscale/video는 HiAPI의 비디오 향상 엔드포인트입니다. 소스 비디오와 지시를 보내면 향상된 비디오를 반환합니다: 더 높은 해상도, 재구성된 정밀 디테일, 그리고 선택적으로 프레임 보간을 통한 더 부드러운 움직임입니다. 소재가 이미 존재하고 문제가 콘텐츠 생성이 아닌 품질일 때 이 엔드포인트를 사용해야 합니다.
적용 시나리오
이 엔드포인트와 자연스럽게 맞는 전형적인 작업:
- 아카이브 및 오래된 소재—— 오래된 녹화물, 압축된 화면 녹화 또는 상속된 미디어가 현대적인 해상도에서 제대로 보여야 할 때.
- 렌더링 파이프라인—— 속도를 위해 낮은 해상도로 먼저 렌더링된 완성 시퀀스를 이후 납품용으로 향상.
- 모션 정리—— 낮은 프레임레이트 소스에 재생 시 끊김을 피하기 위해 보간 프레임이 필요할 때.
- 납품 변형—— 하나의 마스터, 여러 출력 계층, 계층별로 향상 적용.
대안 대신 이것을 선택할 시점
결정은 보통 세 가지 질문으로 귀결됩니다:
- 문제가 해상도와 디테일에 있는가, 아니면 콘텐츠에 있는가? 촬영된 적 없는 장면처럼 새로운 픽셀을 창조해야 한다면 잘못된 도구입니다. 향상은 기저에 실제 소스 프레임이 있다고 가정합니다.
- 파이프라인이 비동기 작업을 감당할 수 있는가? 비디오 작업은 즉각적이지 않습니다. 사용자 경험이 1초 미만 응답을 요구한다면 이 엔드포인트는 요청 핸들러가 아닌 백그라운드 작업에 두어야 합니다.
- 프레임 보간과 업스케일링이 모두 필요한가? 모션 부드러움이 중요하다면 여러 독립 도구를 연결하는 대신 한 번의 처리에서 두 기능을 모두 얻기를 원할 것입니다.
topaz-upscale/video는 둘 다 커버합니다.
소스가 단일 정지 이미지라면 이미지 업스케일러를 대신 사용하세요. 소스 자체는 괜찮지만 인코딩이 나쁘다면 먼저 인코딩을 고치세요—— 향상은 심한 압축이 이미 파괴한 디테일을 복구할 수 없고, 컴퓨팅 비용을 지불하고도 품질 향상을 얻지 못합니다.
첫 호출 전 요청 준비
대부분의 첫 호출 실패는 나쁜 프롬프트가 아니라 빠진 요소에서 비롯됩니다. 코드를 작성하기 전에 이것들을 준비하세요.
계정과 자격 증명
topaz-upscale/video에 접근 권한이 있는 HiAPI API 키가 필요합니다. 키는 소스 코드가 아닌 환경 변수에 보관하세요—— 아래 모든 예제는 환경에서 HIAPI_API_KEY를 읽습니다.
export HIAPI_API_KEY="your-key-here"
접근 가능한 소스 미디어
모델이 입력을 가져올 수 있어야 합니다. 두 가지 신뢰할 수 있는 방식:
- 공개 또는 서명 URL—— 서비스가 대화형 인증 없이 다운로드할 수 있는 URL. 저장소에 서명 링크가 필요하다면 유효 기간이 넉넉한 링크를 생성하고, 재시도 시 다시 생성해야 함을 기억하세요. 그렇지 않으면 긴 작업이 중간에 실패합니다.
- 먼저 업로드—— 플랫폼의 업로드 메커니즘으로 파일을 푸시하고 반환된 식별자를 참조합니다. 대용량 파일과 사설 네트워크 뒤의 모든 것에 더 안전한 선택입니다.
확인할 가치가 있는 소스 특성
호출 비용을 지출하기 전에 확인하세요:
- 길이. 긴 비디오는 긴 작업을 의미합니다. 테스트 중이라면 소스 중간에서 5–10초 클립을 잘라내세요—— 중간이 보통 시작 프레임보다 대표성이 높습니다.
- 코덱과 컨테이너. 희귀 코덱은 때때로 디코딩되지 않을 수 있습니다. 의심스러우면 일반 컨테이너로 리먹싱하세요.
- 프레임레이트. 정확히 기록하세요. 프레임 보간 추론 시 사용됩니다.
- 해상도. 정확한 소스 크기를 기록하여 전후 비교가 정직하도록 하세요.
출력 목표 명확화
첫 호출전에 출력 해상도와 프레임레이트를 정하세요, 이후가 아닙니다. 720p 소스를 1080p로 올리는 합리적인 향상 설정은 480p 소스를 4K로 올리는 설정과 다릅니다. 목표를 적어두세요; 이후 모든 요청에서 재사용하게 됩니다.
curl로 호출하기
요청은 topaz-upscale/video 엔드포인트에 JSON 본문을 담아 POST하는 것입니다. 다음은 완전히 실행 가능한 예제입니다—— 자신의 미디어 URL로 바꾸세요.
curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "topaz-upscale/video",
"input": {
"video": "https://your-bucket.example.com/clips/source_720p.mp4"
},
"parameters": {
"target_resolution": "1080p",
"target_fps": 60,
"interpolation": "smooth",
"detail": "balanced"
},
"prompt": "직물과 피부의 정밀한 질감을 복원하고, 그레인은 자연스럽게 유지하며, 고스팅 없이 60fps로 보간"
}'
응답 해석
즉각적인 응답은 작업을 확인합니다. 작업 식별자와 상태 필드를 받습니다. 비디오 작업은 비동기이므로 실제 패턴은:
# 1. 제출하고 작업 id 캡처
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | jq -r '.id')
# 2. 상태가 종료 상태가 될 때까지 폴링
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'
결과를 읽을 때 세 가지 필드가 중요합니다:
status—— 대기에서 실행, 종료 상태로. 인식할 수 없는 상태는 성공이 아닌 "계속 기다림"으로 취급하세요.output—— 성공 시 존재하며, 향상된 비디오의 URL 또는 식별자를 포함합니다.error—— 실패 시 존재합니다. 메시지를 문자 그대로 읽으세요; 보통 문제가 된 필드를 지적합니다.
프롬프트를 반복 중이라면 요청 본문을 파일(request.json)에 넣고 -d @request.json을 사용하세요. 이렇게 하면 셸 기록이 깨끗하게 유지되고 동일 요청의 여러 버전을 diff할 수 있습니다.
Python에서 같은 엔드포인트 호출하기
Python 버전은 동일한 HTTP 계약의 얇은 래퍼입니다. requests를 사용하고, 키를 환경에 보관하며, 제출과 폴링 루프를 함수로 감싸 호출자가 비동기임을 알 필요가 없도록 하세요.
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def enhance_video(
video_url: str,
prompt: str,
target_resolution: str = "1080p",
target_fps: int = 60,
poll_interval: float = 5.0,
timeout: float = 1800.0,
) -> str:
payload = {
"model": "topaz-upscale/video",
"input": {"video": video_url},
"parameters": {
"target_resolution": target_resolution,
"target_fps": target_fps,
"interpolation": "smooth",
"detail": "balanced",
},
"prompt": prompt,
}
resp = requests.post(f"{BASE}/video/enhance",
headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
job_id = resp.json()["id"]
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
if data["status"] == "succeeded":
return data["output"]["video"]
if data["status"] == "failed":
raise RuntimeError(data.get("error", "향상 실패"))
time.sleep(poll_interval)
raise TimeoutError(f"작업 {job_id}이(가) 예상 시간 내에 완료되지 않았습니다")
실제 파이프라인에서 사용할 때의 주의사항
- 폴링에 지수 백오프 사용. 고정 5초 간격은 셸 스크립트에는 괜찮지만, 프로덕션에서는 백오프하고 간격 상한을 두세요. 긴 비디오는 시간이 걸릴 수 있으며, 더 자주 폴링한다고 빨라지지 않습니다.
- 멱등성. 제출 호출이 타임아웃되면 작업이 시작되었는지 알 수 없을 수 있습니다. 요청 본문과 작업 id를 함께 기록하여 중복을 대조하고, 무작정 재제출하지 마세요.
- 작업 id 영속화. 받는 즉시 데이터베이스에 기록하세요. 프로세스가 폴링 중에 죽으면 두 번째 향상 비용을 지불하지 않고 id로 복구할 수 있습니다.
프레임 보간용 프롬프트 레시피
프레임 보간은 프롬프트가 가장 쉽게 잘못되는 곳입니다—— 무엇도 이끌 수 없을 만큼 모호하거나, 모델이 모순된 목표를 추구하게 할 만큼 과도하게 규정적일 수 있습니다. 프롬프트는 구조화된 파라미터와 공존합니다; 표현은 의도와 모션 특성에 두고, 수치 목표는 파라미터가 담당하게 하세요.
패턴: 수학이 아닌 모션을 설명하기
나쁨:
interpolate
좋음:
부드러운 60fps로 보간합니다. 원본 모션 리듬을 유지하세요—— 속도를 변경하지 마세요. 팬과 카메라 모션은 선형적이고 안정적이어야 합니다; 프레임 가장자리의 왜곡을 피하세요.
이미 parameters에서 목표 프레임레이트를 API에 알렸습니다. 프롬프트는 이 소재의 부드러운 모션이 어떻게 보여야 하는지를 설명해야 합니다.
패턴: 피해야 할 아티팩트 명시하기
24p를 60fps로 부드럽게 만드세요. 빠르게 움직이는 손의 고스팅을 피하고, 난간이나 머리카락 같은 얇은 물체 주변의 잔상을 피하세요. 정적 배경은 완전히 정지 상태를 유지해야 합니다.
구체적인 실패 모드를 명시하는 것이 "고품질"보다 훨씬 효과적입니다. 모델은 구체적인 지시에 비추어 자기 출력을 점검할 수 있습니다.
패턴: 모션과 질감 분리하기
이번 라운드는 모션 부드러움에만 집중하세요. 기존 디테일과 그레인은 그대로 유지하세요—— 질감 복원은 별도로 처리합니다.
두 처리 단계를 연결할 때 유용하며, 각 프롬프트가 하나의 책임만 갖도록 합니다.
패턴: 혼합 모션 소재 처리하기
고정 카메라이지만 피사체가 움직이는 인터뷰 클립은 카메라 정지를 명시하면 잘 작동합니다:
60fps로 보간하세요. 카메라는 고정—— 배경은 완전히 움직이지 않거나 깜빡이지 않아야 합니다. 말하는 사람의 머리와 손만 부드러운 모션을 보여야 합니다.
장문을 쓰고 싶은 충동을 억제하세요. 목표 모션, 피할 아티팩트, 반드시 정지해야 할 내용을 다루는 세 문장이면 거의 모든 경우를 커버합니다.
디테일 재구성용 프롬프트 레시피
디테일 재구성은 작업 중 그럴듯한 정밀 구조를 창조하는 절반입니다. 실패 모드는 환각 질감입니다: 피부가 플라스틱처럼 보이고, 식생이 노이즈가 되며, 텍스트가 깨진 문자처럼 됩니다. 프롬프트는 창조에 상한을 두어야 합니다.
패턴: 소스에 고정하기
소스 프레임과 일치하는 디테일을 재구성하세요. 원본 픽셀이 암시하지 않은 질감을 창조하지 마세요. 디테일이 실제로 손실된 곳에서는 선명하게 만든 노이즈보다 부드럽고 믿을 만한 결과를 우선하세요.
이 한 가지 지시가 대부분의 과도한 선명화 병리를 방지합니다.
패턴: 화면 속 재질 명시하기
직물 질감, 머리카락 가닥, 피부 모공의 정밀한 디테일을 복원하세요. 피부 톤은 자연스럽게, 모공은 불규칙하게 유지하세요—— 매끄럽고 에어브러시 같은 외관을 피하세요. 금속 표면은 기존 하이라이트를 유지하고 새로운 하이라이트를 만들지 않아야 합니다.
재질에 대한 지시는 일반적인 문단 없이도 모델에 실행 가능한 제약을 제공합니다.
패턴: 텍스트와 그래픽 보호하기
이 클립에는 화면 자막과 로고가 포함되어 있습니다. 텍스트는 선명하게 읽을 수 있어야 하며 왜곡되지 않아야 합니다. 그래픽 요소의 스타일을 다시 그리거나 변경하지 마세요.
텍스트는 가장 위험한 디테일입니다—— 깨진 자막이 약간 흐린 자막보다 나쁩니다. 가독성이 중요하다면 프롬프트를 신뢰하지 말고 비교 단계에서 검증하세요.
패턴: 의도적으로 선명도 조절하기
절제된 디테일 복원량을 적용하세요. 목표는 1080p에서 자연스럽게 보이는 소재이며, 선명하게 만든 정지 프레임이 아닙니다. 약간의 부드러움은 허용됩니다; 링잉과 광晕는 허용되지 않습니다.
둘 결합하기
한 번의 처리에서 보간과 재구성을 동시에 할 때는 두 가지를 모두 다루는 프롬프트를 작성하되, 각 절이 하나의 관심사만 다루게 하세요:
직물, 머리카락, 피부의 정밀한 질감을 소스와 일치하게 재구성하고 플라스틱 같은 매끄러움을 피하세요. 60fps로 보간하고, 모션은 안정적이며, 손에 고스팅이 없고, 배경은 완전히 정지 상태여야 합니다.
출력 전후 비교하기
단일 프레임에서 멋져 보이는 향상된 비디오는 움직임에서 무너질 수 있습니다. 고정된 비교 프로세스를 구축하고 파라미터나 프롬프트를 변경할 때마다 실행하세요; 그렇지 않으면 추측하는 것이고 비싼 추측 비용을 치르게 됩니다.
표준 테스트 클립 세트 구축하기
세 개의 짧은 클립(각 5–10초)을 선택하고 절대 변경하지 마세요:
- 쉬움—— 조명이 좋고, 느린 모션, 깨끗한 소스. 거의 완벽해 보여야 합니다; 그렇지 않다면 어딘가 구성이 잘못된 것입니다.
- 어려움—— 빠른 모션, 정밀한 디테일 또는 혼합 모션 유형. 보간 아티팩트가 여기서 나타납니다.
- 적대적—— 화면 텍스트, 얇은 구조 또는 심한 사전 압축. 환각이 여기서 드러납니다.
모든 프롬프트나 파라미터 변경에 대해 세 가지 모두 실행하세요. 쉬운 클립에 도움이 되지만 적대적 클립을 해치는 변경은 개선이 아닙니다.
이 순서로 비교하기
- 100% 확대 나란히 비교. 창에 맞추기를 사용하지 마세요, 아티팩트가 숨습니다. 동일한 크롭 영역을 확인하세요: 얼굴, 텍스트 영역, 고모션 영역.
- 프레임별 드래그. 빠른 모션 부분을 프레임 단위로 넘기며 고스팅, 왜곡, 깜빡임을 찾으세요.
- 실시간 속도 재생. 많은 아티팩트가 프레임별 드래그에서는 사라지고 모션에서는 나타나며, 그 반대도 마찬가지입니다. 둘 다 보세요.
- 텍스트 가독성 검사. 향상된 버전의 모든 자막을 소스와 대조해 읽으세요. 사용 가능한 가장 빠른 객관적 통과/실패 검사입니다.
품질과 비용 모두 고려하기
과금은 엔드포인트가 수행하는 작업을 따릅니다—— 출력 길이와 해상도가 주요 요인입니다; 현재 요금은 웹사이트의 가격 패널을 확인하세요. 실제 결과: 긴 클립의 한계적 품질 향상은 보통 짧은 클립의 명확한 향상보다 거래 가치가 낮습니다. 각 후보 구성에 대해 생성한 출력 길이와 해상도를 기록하고, 보이는 개선이 그 비용에 값하는지 물으세요. 승자를 유지하고 나머지는 버리며, 엔드포인트를 자동화 파이프라인에 연결하기 전에 하나의 구성을 동결하고 기록하세요—— 프롬프트, 파라미터, 테스트 결과—— 이후 변경을 대조 측정할 수 있도록.
흔한 요청 문제 해결하기
topaz-upscale/video와의 대부분의 통합 마찰은 몇 가지 범주로 나눌 수 있습니다. 이 순서로 처리하세요.
인증과 접근
401은 키가 누락되었거나, 형식이 잘못되었거나, 전송되지 않았음을 의미합니다—— 환경 변수가 편집기가 아닌 명령을 실행하는 셸에 실제로 설정되어 있는지 확인하세요. 403은 보통 키는 유효하지만 계정에 이 모델에 대한 접근 권한이 없음을 의미합니다. 모델 이름이 정확히 topaz-upscale/video로 철자되었는지 확인하세요.
서비스가 비디오를 가져올 수 없음
가장 흔한 실패입니다. 증상: 작업이 초기에 다운로드 또는 입력 오류로 실패. 원인:
- URL이 사설이거나 대화형 로그인이 필요합니다.
- 서명 URL이 작업이 다운로드 단계에 도달하기 전에 만료됨—— 긴 대기열에서 특히 가능합니다.
- 호스트가 자동 요청을 차단하거나 타임아웃될 만큼 느립니다.
수정: 플랫폼을 통해 파일을 업로드하고 반환된 식별자를 참조하거나, 제출 시 유효 기간이 넉넉한 서명 URL을 생성하세요.
디코딩 실패
오류가 요청이 아닌 미디어를 언급하면 소스를 일반 컨테이너로 리먹싱하고 재시도하세요. 먼저 로컬에서 파일을 테스트하세요—— 자신의 플레이어도 어려워한다면 서비스도 마찬가지입니다.
작업이 계속 실행되거나 타임아웃됨
긴 소스는 오래 걸리고 일부 요청은 불균형적으로 오래 걸립니다. 재제출 전에 id로 작업 상태를 확인하세요—— 실패한 작업이 아닌 대기 중인 작업을 보고 있을 수 있습니다. 무작정 재제출하면 비용이 두 배가 될 수 있습니다. 스크립트에서 폴링한다면 클라이언트 타임아웃이 예상 작업 시간보다 길도록 하세요, 그렇지 않으면 여전히 정상 실행 중인 작업을 포기하게 됩니다.
출력이 소스보다 나빠 보임
요청은 성공했지만 결과가 과도하게 선명하거나 플라스틱 같거나 고스팅이 있습니다. 이는 API 문제가 아닌 프롬프트 문제입니다: 디테일 재구성 및 보간 레시피로 돌아가 명확한 상한을 추가하세요—— "소스와 일치", "고스팅 없음", "배경은 정지 상태 유지". 그런 다음 표준 비교 세트를 다시 실행하세요.
간헐적이고 재현 불가능한 실패
모든 호출 시 전체 요청 본문과 작업 id를 함께 기록하세요. 둘 다 없으면 실패가 다른 페이로드에서 왔는지 일시적 서비스 문제에서 왔는지 판단할 수 없습니다. 십여 건의 기록된 실패가 있으면 패턴이 보통 몇 분 안에 드러납니다.