Recraft Creative Upscale API 사용 방법: curl, Python 그리고 실제 실행 한 번

TL;DR

• recraft/creative-upscale은 이미지를 확대하고 그 질감과 세부 사항을 다시 그립니다. 요청 본문에는 image_url 필드 하나만 있습니다. 프롬프트도, 배율 설정도 없습니다.
• 통합된 /v1/tasks 흐름을 따릅니다: POST로 taskId를 받고, GET /v1/tasks/<taskId>를 폴링한 뒤, data.output[0].url에서 다운로드합니다.
• 저희 실행에서 1254×1254 PNG가 약 60초 후 4096×4096 WebP, 약 19.8 MB로 반환되었습니다. 대기 시간과 파일 크기를 예산에 넣으세요.

준비해야 할 것

콘솔에서 hiapi API 키를 받고, 공개적으로 접근 가능한 이미지 URL을 준비하세요. 모델 페이지에 입력 제한이 나열되어 있습니다: PNG 권장, 최대 20 MB, 각 변 256–4096 px, 최대 16 MP.

텍스트, 로고, 제품 세부 사항이 원본 그대로 유지되어야 한다면 Recraft Crisp Upscale을 대신 사용하세요. Creative Upscale은 다시 그리기 때문에 작은 요소가 바뀔 수 있습니다.

가장 간단한 curl 요청

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

응답은 작업 핸들입니다:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"},"message":"success"}

data.status가 success가 될 때까지 폴링하세요:

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: 제출, 폴링, 저장

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: keep polling the SAME taskId
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

프로덕션 환경에서는 두 가지 세부 사항이 중요합니다. 첫째, 타임아웃 후 절대 다시 제출하지 마세요: 제출할 때마다 새로운 과금 작업이 생성되므로 taskId를 유지하고 다시 폴링하세요. 둘째, 파일을 즉시 저장하세요; 출력 URL에는 expireAt이 붙어 있고 호스트는 임시입니다.

프로덕션 환경 유의 사항

• 대량 작업에는 콜백을 사용하세요. 폴링 대신 작업 본문에 callback: {"url": "...", "when": "final"}을 넣어 hiapi가 작업 종료 시 호출하게 할 수 있습니다. taskId를 중복 제거 키로 사용하세요.
• 5초 폴링 간격이면 충분합니다. 작업 하나에 약 1분이 걸리므로 더 빠른 폴링은 요청만 늘릴 뿐입니다.
• 제출 전에 URL을 검증하세요. 플랫폼이 형식이 잘못된 URL을 미리 거부하지만(아래 참조), 접근 불가능한 https:// URL은 또 다른 실패 유형이며, 빠른 HEAD 요청으로 미리 잡아내는 것이 좋습니다.

실제 실행 한 번에서 본 것

모델 페이지의 예시 입력 이미지(1254×1254 산속 오두막 PNG)로 실제 요청을 한 번 실행했습니다.

항목	관찰 결과
제출 응답	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
상태 시퀀스	handling → archiving → success
created에서 completed까지 걸린 시간	61초 (1792721625 → 1792721686)
출력	이미지 한 장, WebP, https://temp.hiapi.ai/.../...-0.webp, 약 7일 후의 expireAt 포함
입력 크기	1254×1254 PNG, 2.7 MB
출력 크기	4096×4096 WebP, 약 19.8 MB

그 실행에서 알아두면 좋은 점:

1. archiving 단계에는 아직 output이 없습니다. 결과가 스토리지로 이동되기 전까지 작업은 몇 번의 폴링 동안 completed와 status: "archiving"을 보고합니다. status == "success"일 때만 output[0].url이 있으므로, 처음 completed 타임스탬프를 봤다고 해서 URL을 읽지 마세요.
2. 결과가 깔끔한 2배가 아닙니다. 1254 px 입력이 4096 px로, 각 변 약 3.3배가 되었습니다. 모델 페이지에도 같은 조합이 나와 있고 배율 필드가 노출되지 않으므로, 출력 크기는 사용자가 아니라 모델이 결정한다고 예상하세요. 정확히 2배가 필요하다면 Crisp Upscale이 그 규칙을 따르는 엔드포인트입니다.
3. 출력 파일이 큽니다. 이미지 한 장에 19.8 MB로, 20 MB 입력 제한이 허용하는 크기를 넘어 다시 바로 입력할 수 없으므로, 크기를 조정하지 않고 출력에 두 번째 처리를 연쇄로 실행하지 마세요.
4. 세부 사항은 선명해지는 것이 아니라 다시 그려집니다. 모델 페이지의 이 이미지 쌍에 대한 설명에 따르면 구도, 조명, 색상은 대체로 유지되지만 통나무, 석조, 난간은 다시 그려지고 일부 작은 요소(예: 현관 옆 나무 한 그루)가 바뀝니다. 브랜드 자산을 교체하기 전에 출력을 검토하세요.
5. 잘못된 URL은 빠르게 실패합니다. "image_url": "not-a-url"을 보내면 즉시 HTTP 400이 반환됩니다: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}. 이 패턴이 저희가 검증한 유일한 검사입니다; 256 px 최소값이나 16 MP 상한은 테스트하지 않았습니다.

작업을 하나만 실행했기 때문에 61초라는 숫자는 단일 샘플이며 벤치마크가 아닙니다.

Creative Upscale인가 Crisp Upscale인가?

둘 다 image_url 하나만 받고 프롬프트가 필요 없습니다. 차이는 픽셀 처리 방식과 가격입니다.

	Creative Upscale	Crisp Upscale
모델 id	recraft/creative-upscale	recraft/crisp-upscale
동작	확대하고 질감과 세부 사항을 다시 그림	가로세로를 2배로 늘리고 내용과 텍스트 유지
적합한 용도	오래된 일러스트, 작은 크기 또는 저해상도 아트워크	제품 사진, 텍스트가 있는 포스터, 디자인 자산
가격	이미지당 훨씬 높음; 가격 참조	Crisp 가격 글 참조

Creative Upscale의 이미지당 가격은 Crisp보다 훨씬 높으므로(실시간 숫자는 가격 페이지에서 비교하세요), 세부 사항이 실제로 재생성되기를 원할 때만 사용하세요. 모델 전반에 걸친 범용 해상도 워크플로는 hiapi로 이미지 해상도 높이기를 참조하세요.

관련 글

• Recraft Creative Upscale 모델 페이지
• Recraft Crisp Upscale API 가이드
• Recraft Remove Background API 가이드: 먼저 확대하고 피사체를 분리
• hiapi API로 이미지 해상도 높이기
• hiapi 가격

FAQ

프롬프트가 필요한가요? 아닙니다. 모델 페이지에는 이미지 한 장 입력만 설명되어 있고 프롬프트나 다른 설정이 없으며, 저희 요청에는 image_url만 사용했습니다.

출력 크기를 선택할 수 있나요? API로는 불가능합니다. 배율 필드가 없으며, 저희 1254 px 입력은 4096 px로 반환되었습니다.

텍스트와 로고가 유지되나요? 보장되지 않습니다. 세부 사항이 재생성되고 작은 요소가 바뀔 수 있으므로 텍스트가 있는 자산에는 Crisp Upscale을 사용하세요.

어떤 출력 형식을 받나요? 저희 실행에서는 WebP였으며, 만료되는 임시 URL로 제공되므로 즉시 다운로드하세요.

얼마나 걸리나요? 저희 단일 실행은 약 1분이었습니다; 이 정도 대기 시간을 기준으로 클라이언트를 구축하세요.