비디오 업스케일링 API: 전달 및 품질 관리 워크플로

마음에 드는 짧은 클립이 있습니다. 480p로 싸게 만들었거나 오래된 자료에서 잘라낸 클립이고, 그 소리는 그대로 유지한 채 1080p나 4K로 내보내야 합니다. 비디오 업스케일링 API는 한 번의 호출로 처리하지만, 그 호출은 작업의 중간일 뿐입니다. 파일을 쓸 수 있는지를 정하는 것은 그 전(편집을 마무리하고 원본을 확인하는 일)과 그 후(제때 내려받고, 크기와 길이와 오디오를 확인하고, 대상이 요구하는 정확한 캔버스로 내보내는 일)입니다.

요약하면, 최종 컷을 대상에 필요한 단계에서 단 한 번만 확대합니다. SpicyAPI Video Upscaler는 3초에서 60초짜리 MP4와 단계를 받아서, 길이와 화면 비율과 움직임과 오디오 트랙을 그대로 유지한 채 같은 클립을 더 높은 해상도로 돌려줍니다. 프롬프트는 없습니다. 가격은 720p 또는 1080p에서 원본당 초당 $0.006, 2K에서 $0.012, 4K에서 $0.024입니다.

무엇을 보내고 무엇을 지불하는가

video_url(MP4로 직접 가는 링크, 또는 업로드한 파일)을 보내고, 필요하면 resolution을 함께 보냅니다. 720p, 1080p(기본값), 2k, 4k 중 하나입니다. 업로드하는 MP4는 최대 90 MB까지 가능합니다. 과금은 원본 클립의 초 단위로 계산하며, 정수 초로 올림하고 3초가 최소입니다.

올림은 제출한 클립마다 따로 적용됩니다. 그래서 5.2초짜리 클립 세 개는 16초가 아니라 18초로 과금됩니다. 제출 전에 보이는 견적은 60초짜리 클립을 전제로 합니다(1080p에서 $0.36, 4K에서 $1.44). 태스크가 정산되면서 쓰지 않은 부분이 해제되므로, 6초짜리 클립은 6초로 과금됩니다. 실패한 태스크는 환불됩니다.

확대의 비용 논리는 생성 쪽에 있습니다. Seedance 2.5 Spicy로 480p에서 생성한 10초짜리 클립은 시도당 $2.16이고, 네이티브 1080p에서는 $10.80입니다. 먼저 480p에서 초안을 만들고, 남길 take를 정한 다음, 1080p로 확대하는 데 $0.06을 더하면 됩니다. 업스케일러는 이미 화면 안에 있는 내용을 키우므로, 초안에 없는 디테일이 나중에 생기지는 않습니다. 작은 라벨이나 얼굴이 정확해야 한다면 초안 단계에서 확인하거나, 더 높은 해상도로 초안을 만드세요.

원본을 준비한다

편집을 먼저 마무리하세요. 확대하기 전에 자르고, 순서를 바꾸고, 오디오를 혼합하세요. 그러지 않으면 이후의 편집을 픽셀 수가 몇 배 많은 파일 위에서 다시 해야 하고, 버릴 초들을 처리하는 비용을 치르게 됩니다. 업스케일러는 잘못된 take를 고칠 수 없습니다. 뒤틀린 손이나 어긋난 로고는 그대로 더 커져서 돌아옵니다.

파일을 확인하세요. ffprobe는 화면에는 "60초"로 올림되어 보이지만 실제로는 60.4인 길이를 포함해, 당신이 정말로 제출하는 내용을 그대로 보여줍니다:

ffprobe -v error \
  -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels \
  -of json approved-source.mp4

확인할 것이 세 가지 있습니다. 길이는 3초에서 60초 사이여야 합니다. 휴대전화 클립은 세로로 재생되는데 저장된 프레임은 가로에 회전 플래그가 붙은 상태일 수 있습니다(ffprobe -show_streams는 이를 side data에 표시합니다). 업로드하기 전에 회전을 적용해 넣으세요. 그리고 오디오 스트림도 기억해 두세요. 나중에 결과와 비교하게 됩니다.

이미 충분히 큰 클립은 건너뛰세요. 해당 단계 이상인 클립은 거의 같은 크기로 돌아오는데도 과금이 됩니다. 720p로 보낸 786x1178 클립은 784x1176으로 돌아왔습니다. 원본이 이미 대상 규격을 만족한다면 그대로 내보내고 끝내세요.

가장 깨끗한 마스터에서 시작하세요. 압축 블록과 노이즈도 다른 모든 것과 함께 커집니다. 생성 마스터나 편집 마스터를 쓰고, 소셜 피드에서 다시 내려받은 사본은 쓰지 마세요.

대상으로부터 단계를 고른다

단계는 화면 비율을 유지한 픽셀 예산입니다. 그래서 일반적인 비율이 아닌 원본은 일반적인 크기가 아닌 크기로 돌아옵니다. 832x480 클립은 1080p에서 1896x1094로, 4K에서 3792x2188로 돌아왔습니다. 854x480 클립은 1922x1080으로 돌아왔습니다. 정확히 1920x1080이 되리라 기대하지 마세요.

• 720p 또는 1080p는 피드, 랜딩 페이지, 광고에 씁니다. 둘은 가격이 같으니 가격이 아니라 대상으로 고르세요. 1080p가 기본값이며 대개 맞는 선택입니다.
• 2K 또는 4K는 큰 디스플레이, 프레젠테이션, 또는 나중에 잘라 쓸 때 씁니다. 가격은 두 배와 네 배이고 시간도 더 걸립니다. 5초짜리 1080p 작업에 약 35초, 4K에 약 100초입니다. 5초짜리 4K 파일은 약 19 MB입니다.
• 대상이 세로 피드용 1080x1920 같은 정확한 캔버스를 요구한다면, 확대 이후의 별도 내보내기 단계로 다룹니다.

가로 클립을 확대한 다음 세로로 자르면, 버리게 되는 픽셀 값을 지불하는 셈입니다. 구도는 확대 전에 정하고 최종 구성을 보내세요.

먼저 Playground에서 해본다

1. Video Upscaler 페이지를 열고 Playground 탭의 Form 뷰에 그대로 머무릅니다. 잔액이 있는 계정으로 로그인해 실행합니다.
2. Input video 아래에 승인된 MP4를 놓거나(최대 90 MB), Asset URL에 파일의 직접 링크를 붙여넣습니다. 동영상을 재생하는 페이지를 넘기면 HTML이 반환되고, 과금은 환불된 채 호출이 실패합니다. 파일을 업로드하는 방법이 가장 확실합니다.
3. Resolution을 720p, 1080p, 2K, 4K 중 하나로 설정합니다. 가격에 영향을 주는 항목으로 표시되며, 견적은 선택에 따라 갱신됩니다.
4. 실행하고, 결과를 원본과 나란히 재생해 보세요(아래 확인 항목 참고). 그다음에야 자기 저장소로 복사합니다.

5초짜리 클립은 4K에서도 몇 센트입니다. 코드를 쓰기 전에, 실제로 내보낼 단계에서 진짜 클립을 시험해 보세요.

그다음 코드로 실행한다

Python SDK를 설치하고(pip install spicyapi), 서버 환경에서 SPICY_API_KEY를 설정한 뒤 실행합니다:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/video-upscaler-v1/upscale",
    input_data={
        "video_url": "https://example.com/approved-product-ad.mp4",
        "resolution": "1080p",
    },
    idempotency_key=str(uuid.uuid4()),  # one key per approved clip and tier
)

print("Resume task:", task["taskId"], flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy the file to your own storage now

생성, 대기, 재시도, 오류 코드, 다운로드는 tasks 가이드와 Python SDK 레퍼런스에 다뤄져 있습니다. 로컬 파일은 무료 업로드 절차를 거쳐 spicy:// URI로 전달됩니다. 결과 링크의 유효 시간은 짧고 파일은 약 14일 동안 보관되므로, 그 위에 뭔가를 쌓기 전에 보관과 전달을 확인하세요. succeeded는 서비스가 일을 끝냈다는 뜻일 뿐입니다. 아래 확인 항목이 모두 통과한 후에 클립을 전달 완료로 표시하세요.

또는 에이전트가 실행하게 한다

어시스턴트가 업스케일을 실행해야 한다면, 공식 도구 세 개 모두 가격을 보여 주고 유료 호출 전에 확인을 요청합니다.

• CLI. {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"}를 input.json에 넣고 다음을 실행합니다:

``bash spicyapi tasks create --model spicyapi/video-upscaler-v1/upscale --input-file input.json --wait ``

CLI 문서를 참고하세요. npx @spicyapi/cli는 설치 없이 동작합니다.

• MCP 서버. MCP 서버를 추가한 뒤 이렇게 물어보세요: "Upscale approved-source.mp4 to 1080p with Video Upscaler." spicyapi_upload_file로 파일을 업로드하고, 가격 확인을 위해 멈추는 spicyapi_task_create를 호출한 뒤, spicyapi_task_wait를 호출합니다.
• Skill. npx skills add spicyapi-ai/spicy-skill는 Agent Skill을 설치합니다. 이 Skill은 코딩 어시스턴트가 필드를 추측하는 대신 현재 모델 스키마를 읽게 합니다.

결과를 원본과 대조해 확인한다

같은 프로브를 두 파일에 실행해서 비교하세요. 클립마다 한 줄씩 출력하는 짧은 스크립트입니다:

probe() {
  ffprobe -v error -of json \
    -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration "$1" |
  jq -c '{size_bytes: (.format.size|tonumber), duration: (.format.duration|tonumber),
    video: (.streams|map(select(.codec_type=="video"))[0]|{codec:.codec_name,w:.width,h:.height,fps:.avg_frame_rate}),
    audio: (.streams|map(select(.codec_type=="audio"))[0]|if .==null then null else {codec:.codec_name,rate:.sample_rate,ch:.channels} end)}'
}
probe approved-source.mp4
probe returned.mp4

확인할 항목:

1. 크기와 모양. 화면 비율이 원본과 맞고, 각 변의 길이가 그 단계에서 나와야 하는 값인지 확인합니다. 실제 너비와 높이를 기록하세요. 단계 이름에서 베끼면 안 됩니다.
2. 길이. 길이가 원본과 맞는지 확인합니다. 대상이 정확한 컷 지점에 의존한다면, 반올림된 숫자만 보지 말고 첫 프레임과 마지막 프레임을 보세요.
3. 오디오. 돌아온 파일에 원본과 같은 채널 수와 같은 길이의 오디오 스트림이 있는지 확인합니다. 스트림이 존재한다는 사실이 옳다는 증거는 아니므로, 두 파일을 같은 위치에서 재생해 보세요. 첫 발화, 컷 지점, 마지막 구절입니다. 원본이 의도적으로 무음이었다면 결과도 무음이어야 합니다.
4. 움직이는 화면. 정지 화면을 살펴보기 전에 클립 전체를 정상 속도로 보세요. 깜빡임, 일렁이는 질감, 움직이는 가장자리의 후광은 재생 중에 나타나고 정지 화면에서는 거의 나타나지 않습니다.
5. 의미를 담는 디테일. 제품 라벨, 로고, 글자, 얼굴은 업스케일러가 실제 디테일을 복원하는 대신 그럴듯한 디테일을 지어낼 수 있는 지점입니다. 같은 자르기 범위로 원본과 비교하세요. 바뀐 브랜드 마크는 아무리 또렷해 보여도 클립을 불합격으로 만듭니다.

한 순간을 나란히 비교하려면, 원본을 실제 픽셀이 보이도록 최근접 이웃 방식으로 출력 크기까지 확대합니다:

ffmpeg -ss 2.0 -i returned.mp4 -ss 2.0 -i approved-source.mp4 \
  -filter_complex "[1:v]scale=1896:1094:flags=neighbor[s];[s][0:v]hstack" \
  -frames:v 1 compare-at-2s.png

확대 비율을 돌아온 너비와 높이에 맞추세요.

정확한 전달 파일을 내보낸다

대상이 고정된 캔버스를 요구한다면, 로컬 내보내기로 마무리합니다. 이 예는 2:3처럼 대략 세로인 원본을 전제로 합니다. 가로 클립을 확대해 1080x1920으로 패딩하면 얇은 띠 형태의 화면이 남습니다. 패딩은 프레임 전체를 보존하고, 자르기는 화면을 채우지만 가장자리를 잘라내므로 어느 쪽이든 제품 상태를 확인하세요.

ffmpeg -i accepted-upscale.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -c:a aac -b:a 192k delivery-vertical.mp4

이 과정은 오디오를 다시 인코딩합니다. 원본 트랙을 그대로 유지해야 한다면 대상이 받아들이는 경우 -c:a copy를 쓰고, 그다음 내보낸 파일에 프로브를 다시 실행하세요. 자막과 그래픽은 확대 후에 굽습니다. 그러면 글자의 가장자리가 확대된 것이 아니라 최종 크기로 그려집니다.

세 개의 파일을 보관하세요. 승인된 원본, 손대지 않은 확대 결과, 그리고 내보낸 파일 각각입니다. 나중에 자르거나 다시 내보내더라도 두 번째 확대 비용이 발생하지 않습니다.

문제가 생겼을 때

확대를 다시 실행하지 말고, 실패한 단계를 고치세요.

일괄 처리 전에 파일 하나를 시험한다

실제 움직임과 오디오 트랙이 있는 클립 하나를 전체 경로로 보내 보세요. 프로브, 확대, 다운로드, 비교, 내보내기, 그리고 실제 대상(피드, 플레이어, 큰 디스플레이)에서 최종 파일을 재생해 봅니다. 로컬 플레이어와 플랫폼은 디코딩과 재압축 방식이 다르므로, 결과가 버틸 수 있는지는 대상만 보여줍니다. 일괄 작업을 짤 때는 빠른 팬, 컷이 많은 광고, 미세한 질감의 클립을 포함하고, 클립마다 원본 길이와 과금된 초 수와 단계와 최종 과금액과 거절 사유를 기록하세요.

단계를 두고 고민한다면, 클립은 그대로 두고 실제로 보게 될 크기에서 1080p와 4K를 비교하세요. 1080p로 이미 대상 요건을 만족한다면, 초당 추가로 드는 $0.018은 눈에 보이는 것을 사주지 않습니다.

판단

돌아온 파일은 완성된 전달물이 아니라 확인할 마스터로 다루세요. 호출 비용은 몇 센트입니다. 피할 수 있는 비용은 더 높은 해상도로 편집을 다시 하는 것, 이미 충분히 큰 클립을 확대하는 것, 그리고 오디오나 제품 라벨이 바뀐 파일을 내보내는 것입니다. 클립을 시험해 보려면 Video Upscaler 모델 페이지를 여세요.