Recraft Crisp Upscale API 사용법? 필드 하나로 2배 확대

TL;DR

• Recraft Crisp Upscale(recraft/crisp-upscale)은 한 가지 일만 합니다: 이미지의 가로·세로를 각각 2배로 확대하고, 가장자리와 텍스처를 더 선명하게 하며, 화면 내용과 텍스트는 그대로 유지합니다. 프롬프트가 없고, 요청 본문에는 image_url 하나만 있습니다. 모델 페이지 열기에서 이미지 한 장을 업로드하면 바로 시험해볼 수 있고, 신규 사용자는 가입 시 200 크레딧을 받습니다.
• 장당 $0.004: 1,000장 $4.00, $10으로 약 2,500장; 입력 이미지 크기는 가격에 영향을 주지 않습니다(전체 가격은 가격 페이지 참조).
• 호출은 HiAPI /v1/tasks 인터페이스로: 작업을 제출해 taskId를 받고, 결과를 조회한 뒤 성공 시 output[0].url에서 다운로드합니다(JPEG, 투명 채널 없음).

할 수 있는 일

• 충실한 확대, 재그리기가 아님: 다이얼 텍스처, 피부 주름, 포스터 작은 글씨 같은 디테일이 더 선명해지지만 내용, 구도, 텍스트는 하나도 바뀌지 않습니다—글자가 있는 소재가 '다른 이미지로 확대'되지 않습니다.
• 필드 하나로 조정: image_url에 공개 주소(JPEG / PNG / WebP, ≤10 MB)를 전달하며, 프롬프트도 배율 옵션도 없습니다.
• 상품 이미지, 글자 있는 포스터, 디자인 소재에 적합: '원본은 이미 맞고 해상도만 부족한' 모든 상황.
• 부적합한 상황도 명확: 4K 수준의 재그리기 디테일을 원하거나 내용도 함께 바꾸고 싶다면 생성형 재그리기를 사용해야 합니다(자세한 내용은 이미지-투-이미지 모델로 해상도를 높이는 영어 튜토리얼 참조); Crisp Upscale은 크기만 2배로 확대하고 내용을 다시 그리지 않습니다.
• 출력은 JPEG 1장; 투명 결과를 원한다면 먼저 확대하고 나서 배경 제거(배경 제거 사용법은 영어판 배경 제거 튜토리얼 참조).

아래는 실제 '원본 → 2배' 한 쌍입니다:

원본 640×640	확대 결과 1280×1280

recraft/crisp-upscale, 640×640 → 1280×1280, $0.004. 다이얼 기요셰 패턴, 브러시드 스틸 케이스, 다이얼 작은 글씨가 2배 크기에서도 여전히 선명합니다.

모델 페이지를 열어 한 장 업로드해 보세요 →

두 가지 시작 방법

브라우저 3단계: 모델 페이지 열기 → 이미지 업로드 → 확대 클릭, 장당 $0.004.

API 3단계: POST /v1/tasks 제출 → taskId 획득 → GET /v1/tasks/<taskId>로 success 확인 후 다운로드. 일괄 처리라면 이 세 단계를 반복하며, 장당 하나의 작업입니다.

curl: 첫 장

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft/crisp-upscale",
  "input": {
    "image_url": "https://static.hiapi.ai/gallery/2026/10/4fdfd6b43b638849.jpg"
  }
}'

요청 본문은 이게 전부입니다—다른 필드(예: prompt, scale)를 더 전달하면 바로 400이 납니다.

Python: 제출, 폴링, 다운로드

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft/crisp-upscale",
    "input": {
        "image_url": "https://example.com/your-image.jpg",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 임시 주소, 가능한 빨리 다운로드해 저장
    img = requests.get(image_url, timeout=60)
    with open("upscaled.jpg", "wb") as f:
        f.write(img.content)
    print("saved upscaled.jpg")

파라미터 표

필드	필수	값	설명
image_url	예	공개 http/https 주소	JPEG / PNG / WebP, 장당 ≤10 MB

이 필드 하나뿐입니다. 확대 배율은 가로·세로 각각 2배로 고정되어 선택할 수 없으며, 프롬프트도 출력 형식 파라미터도 없습니다.

마주치게 될 오류

상태 코드	의미	처리 방법
400 INVALID_REQUEST	image_url 누락, http/https 주소가 아님, 또는 prompt / scale 같은 존재하지 않는 필드를 추가로 전달함	요청 본문에 image_url만 남기기
402 INSUFFICIENT_QUOTA	잔액 부족(과금 없음)	충전 후 다시 시도
429 RATE_LIMITED	요청 제한 발생	제출 빈도 낮추기
409 / 422 IDEMPOTENCY_KEY_*	동일한 멱등 키로 중복 제출	새 Idempotency-Key로 변경

작업 최종 실패에는 TASK_FAILED, TASK_TIMEOUT 등의 오류 코드도 있습니다; 실패 시 과금되지 않습니다.

출시 전 주의 사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 최종 상태를 자동으로 알려줍니다.
• 즉시 이전 저장: output[0].url은 임시 주소이므로 받자마자 다운로드하세요.
• 소요 시간: 장당 보통 10초에서 1분 정도이니, 폴링 간격을 너무 짧게 설정하지 마세요.
• 투명 채널: 출력은 JPEG로 투명을 포함하지 않습니다; 투명 배경 소재가 필요하면 먼저 확대하고 나서 배경을 제거하세요(순서가 반대면 누끼 가장자리가 흐려집니다).
• 일괄 비용 계산은 간단: 한 SKU의 다섯 장 이미지를 모두 확대하면 $0.02; 매장 전체 1,000장 소재를 한 번에 돌리면 $4.00이며, 일괄 제출하면 되고 장당 작업이 개별로 시간이 측정됩니다.
• 원본 품질이 상한을 결정: 2배 확대는 가장자리를 더 선명하게 하지만, 원본이 뭉개진 부분이 허공에서 디테일이 생기지는 않습니다; 중요한 소재는 한 장으로 먼저 시험한 뒤 일괄 처리하세요.

자주 묻는 질문

정말 2배인가요?

네. 가로·세로를 각각 한 배 확대합니다(640×640 → 1280×1280, 480×640 → 960×1280). 배율은 고정이며 4배 옵션은 없습니다; 더 크게 필요하면 확대 후 한 번 더 실행하세요.

화면 속 텍스트가 바뀌나요?

아니요. 글자가 있는 포스터를 확대해도 글자 형태는 그대로 유지되며, 다시 쓰거나 텍스트를 추가하지 않습니다.

장당 얼마인가요?

장당 $0.004, 1,000장 $4.00; 입력 이미지 크기는 가격에 영향을 주지 않습니다. 실패 시 과금되지 않으며, 파라미터 검증을 통과하지 못하면 과금에 들어가지 않습니다.

base64를 전달할 수 있나요?

아니요. image_url은 공개 http/https 주소여야 합니다; 로컬 파일은 먼저 본인 스토리지에 업로드한 뒤 주소를 제공하세요.

한 장에 얼마나 걸리나요?

보통 10초에서 1분 정도; 일괄 작업은 장수에 따라 대기열에 들어가므로, 급하면分批 제출하세요.

다음 단계: 본인 상품 이미지 한 장을 모델 페이지에서 확대해 결과를 확인하고; 다섯 쌍의 '원본 → 2배' 실제 비교는 사례 페이지에서; 생성형 재그리기와 동일 원본 비교는 비교 페이지에서 확인하세요.