이미지 업스케일링 API: 2K·4K·8K 선택 후 결과 다운로드

완성된 이미지 한 장을 키우려면 spicyapi/image-upscaler-v1/upscale을 씁니다. 최종 크롭에 필요한 픽셀 수에 따라 2k, 4k, 8k 중에서 고르세요. 각 단계는 대략 4, 17, 67메가픽셀의 픽셀 예산이며, 고정된 긴 변 길이가 아닙니다. 세 단계 모두 출력 이미지당 $0.012입니다(1000장이면 $12). 형식은 JPEG, PNG, WebP입니다. 먼저 Playground에서 시험해 보고, 그다음 짧은 Python 예제를 실행하거나 Agent에 맡기세요.

최종 크롭으로 단계를 고르세요

Image Upscaler는 원본의 화면 비율을 그대로 유지합니다. 1024×1536 세로 사진은 다음 결과를 반환합니다.

화면 비율이 달라지면 치수도 달라집니다. "2배"나 "4배"로 생각한다면, 선형 확대율은 픽셀 예산의 제곱근을 원본의 메가픽셀 수로 나눈 값입니다.

원본 픽셀 수보다 낮은 단계는 이미지를 축소합니다. 3344×5017 입력을 2k로 보내면 1672×2509가 돌아옵니다. 원본이 이미 목표 치수를 만족한다면 평소대로 내보내면 됩니다. 이 엔드포인트에는 원본 크기 그대로 선명하게 만드는 모드가 없습니다.

2배 밀도로 너비 600픽셀로 보여 주는 웹 카드라면 최종 크롭에 1200픽셀이 필요합니다. 그 크롭이 원본 너비의 절반만 쓴다면 마스터는 너비 2400픽셀이 필요합니다. 2k의 1672픽셀 세로 사진으로는 부족하고, 4k면 해결됩니다.

인쇄라면 치수에 프린터가 요구하는 밀도를 곱하세요. 10×15인치 이미지를 인치당 300픽셀로 만들려면 3000×4500픽셀이 필요한데, 4k 세로 사진은 크롭 없이 이 크기를 덮습니다. 밀도 메타데이터를 바꿔도 픽셀이 늘어나지 않으며, 크롭을 더 촘촘하게 하면 계산을 다시 해야 합니다.

8k는 크롭이 필요로 할 때만 고르세요. 가격은 같지만 67메가픽셀은 약 268 MB의 4채널 원시 픽셀 데이터라 편집 메모리에 영향을 주고, 이 단계에서 내려받는 JPEG는 약 8 MB에 이릅니다.

깨끗한 원본을 준비하세요

물체 제거, 크롭, 그 밖의 편집을 먼저 끝내고, 웹사이트 썸네일이 아니라 가장 좋은 원본에서 시작하세요. 입력은 10 MB 이하인 JPEG, PNG, WebP 한 장이므로, 큰 인쇄용 마스터는 보내기 전에 내보내야 할 수 있습니다. 가상의 문구류 카탈로그를 다룬다면 승인된 만년필 사진을 상자와 함께 쓰고, 정확한 각인 이름은 별도 참고 자료로 보관하세요. 확대는 모호한 흔적을 확신에 찬 잘못된 글자로 바꿔 버릴 수 있습니다.

다음 단계에 맞춰 output_format을 고르세요. jpeg(기본값)가 가장 작고, PNG는 무손실이지만 8k에서는 몇 배 커지며, WebP는 그 중간입니다. PNG로도 재구성된 디테일이 사실이 되지는 않습니다. 프롬프트도, 정확한 너비/높이도, 얼굴 복원 강도도, 시드도 없습니다.

확인 영역 일러스트이며, 업스케일링 결과물이 아닙니다.

먼저 Playground에서 시험하세요

1. Image Upscaler 페이지를 열고 Playground 탭의 Form 뷰에 머무르세요. 실행하려면 잔액이 있는 계정으로 로그인합니다.
2. 이미지를 Input image(JPG, PNG, WEBP, 최대 10 MB)에 놓거나 Asset URL로 링크를 붙여 넣습니다.
3. Resolution을 2K, 4K, 8K 중 하나로, Output format을 JPEG, PNG, WebP 중 하나로 설정합니다.
4. 실행한 뒤 최종 카드 크기나 인쇄 크기로 결과를 확인합니다.

코드를 쓰기 전에 여기서 최선의 원본을 시험해 보세요. Playground의 요청 본문은 API가 받는 것과 같은 JSON이므로, 여기서 통과한 설정은 그대로 코드로 옮길 수 있습니다.

그다음 코드에서 호출하세요

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

이 예제의 다운로드 검증에는 Pillow(python -m pip install Pillow)가 필요합니다. 원래 출력 파일은 새 JPEG가 정상적으로 디코딩된 뒤에만 교체됩니다.

import os
from pathlib import Path
import tempfile
import urllib.request
import uuid

from PIL import Image

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

source = client.upload_file("./fountain-pen-master.png")  # local file becomes a spicy:// URI

task = client.create_task(
    model="spicyapi/image-upscaler-v1/upscale",
    input_data={"image_url": source["uri"], "resolution": "4k", "output_format": "jpeg"},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)

print(f"Task ID: {task['taskId']}", flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

assets = [a for a in output_assets(final)
          if a.get("url") and not a.get("pending") and not a.get("unavailable")]
if not assets:
    raise RuntimeError(f"Task {task['taskId']} has no downloadable output yet")

request = urllib.request.Request(assets[0]["url"], headers={"User-Agent": "upscale-example/1.0"})
target = Path("upscaled.jpg")
temporary = None
try:
    with tempfile.NamedTemporaryFile(dir=target.parent, suffix=".jpg", delete=False) as out:
        temporary = Path(out.name)
        with urllib.request.urlopen(request, timeout=60) as response:
            out.write(response.read())
    with Image.open(temporary) as image:
        if image.format != "JPEG":
            raise ValueError("Expected a JPEG output")
        image.load()  # reject unreadable or truncated data before replacing the keeper
    os.replace(temporary, target)
finally:
    if temporary is not None:
        temporary.unlink(missing_ok=True)

한 번 실행하면 약 45초가 걸립니다. resolution과 output_format을 바꾸면 단계나 형식을 전환할 수 있습니다. 업로드, 대기, 재시도, 오류는 tasks 가이드와 Python SDK 레퍼런스에 정리돼 있습니다. 결과 링크는 약 20분 뒤 만료되고 생성 파일은 늦어도 14일 후 삭제되므로, 결과를 직접 보관 공간에 복사하세요.

또는 Agent에게 맡기세요

어시스턴트가 이미지를 확대해야 할 때, 공식 도구 세 개 모두 가격을 보여 주고 유료 호출 전에 확인을 요청합니다.

• CLI. spicyapi는 터미널에서 작업 하나를 실행합니다(npx @spicyapi/cli는 설치 없이도 동작). 업로드가 출력한 URI를 이용해 {"image_url": "spicy://...", "resolution": "4k"}를 input.json에 넣으세요.

``bash spicyapi files upload ./fountain-pen-master.png spicyapi tasks create --model spicyapi/image-upscaler-v1/upscale --input-file input.json --wait ``

• MCP 서버. 어시스턴트에 MCP 서버를 추가한 뒤 "Upscale ./fountain-pen-master.png to 4K with Image Upscaler."라고 물어보세요. spicyapi_upload_file을 호출하고, 이어서 가격 확인을 위해 spicyapi_task_create에서 멈춘 뒤, spicyapi_task_wait를 호출합니다.
• Skill. npx skills add spicyapi-ai/spicy-skill은 Agent Skill을 설치합니다. 이 스킬은 코딩 어시스턴트가 필드를 추측하지 않고 현재 모델 스키마를 읽게 합니다. 그 자체로 작업을 실행하지는 않으니 CLI나 MCP와 함께 사용하세요.

추가된 픽셀이 쓸모 있는지 판단하세요

먼저 최종 카드 레이아웃이나 인쇄 배치에서 결과를 보고, 그다음 펜촉과 각인, 상자 가장자리를 실제 크기로 확인하세요. 추가된 픽셀이 그 용도에 도움이 되면서 제품의 정확성도 지켰습니까?

비교할 초상화 디테일을 그린 일러스트이며, 복원된 얼굴 디테일이 아닙니다.

가상의 성인 초상화에 대해 SpicyAPI는 이 도구에서 안전 필터를 실행하지 않으므로, 동의와 법적 의무는 사용자에게 남습니다. 중간 수위와 고수위 NSFW 입력도 정상적으로 확대되며, 일괄 처리 전에 자신의 자료로 한 번 먼저 실행해 보세요.

마스터는 괜찮은데 작은 카드에서 각인이 사라진다면, 그 파생 이미지를 조정하거나 줌을 줄이세요. AI를 한 번 더 돌리는 것이 첫 번째 해결책은 아닙니다. 더 많은 픽셀 대신 더 넓은 구도가 필요하다면 새 화면 비율로 확장하기를, 클립은 영상 업스케일링을 참고하세요.