블로그

사용 가이드

recraft/crisp-upscale 시작 가이드: 이미지 확대 API의 연동 핵심과 과금

능력 경계부터 장당 과금까지, 개발자가 이미지 확대를 운영 흐름에 안정적으로 연동하는 방법

Nov 16, 2026
짙은 커피색 바탕 위에 오트밀색과 갈색의 넓은 직조 밴드가 교차하는 바스켓 위브 패턴의 플랫 커버 이미지로, 이미지 업스케일 API 가이드 주제와 어울립니다
모델
recraft-crisp-upscale
이 페이지에서

crisp-upscale이 해결하는 문제

이미 존재하지만 해상도가 부족한 이미지를 더 크고 가장자리가 더 선명한 버전으로 바꾸는 것—이것이 recraft/crisp-upscale의 역할입니다. 이 모델은 image-to-image(이미지 대 이미지) 카테고리에 속합니다. 이미지를 주면 확대된 이미지를 돌려줍니다. 입력에 텍스트 프롬프트 자리는 없고 출력 유형은 이미지로 고정됩니다.

이런 모델이 해결하는 문제는 매우 구체적입니다:

  • 소재 크기가 제각각입니다. 사용자가 업로드한 이미지, 기존 콘텐츠 라이브러리의 이미지, 제3자 협력사가 제공한 이미지의 해상도가 들쭉날쭉한데 프런트엔드 표시 크기는 디자인 요구로 고정되어 있습니다.
  • 오래된 콘텐츠를 재활용해야 합니다. 몇 년 전의 삽화, 스크린샷, 썸네일을 더 큰 컨테이너에 그대로 넣으면 흐려집니다.
  • 생성 결과의 마무리. 모든 이미지 생성 또는 편집 파이프라인의 끝에는 최종 크기로 전달하기 위한 확대 단계가 필요할 수 있습니다.

필요가 '한 문장으로 이미지 한 장 생성하기'라면 이 모델의 범위가 아닙니다. 필요가 '이미지가 있는데 더 크고 선명하게 만들고 싶다'라면 여기에 해당합니다. 판단 기준은 간단합니다: 호출 전에 구체적인 이미지 파일이 이미 손에 있는가. 있다면 이 모델이고, 없다면 먼저 다른 곳에서 생성 문제를 해결해야 합니다.

개발자에게 이런 단일 책임은 오히려 좋은 일입니다: 인터페이스 의미가 단순하고 입출력 구조가 안정적이며 실패 원인을 더 쉽게 찾을 수 있습니다. 확대는 독립적으로 테스트하고 독립적으로 롤백할 수 있는 단계로, 프롬프트 엔지니어링과 얽히지 않습니다.

왼쪽의 작은 격자는 저해상도 입력을 나타내고, 오른쪽의 확대된 선명한 격자는 crisp-upscale의 확대와 샤프닝을 보여줍니다

능력 경계: 무엇을 할 수 있고 무엇을 기대하지 말아야 하는가

crisp-upscale을 '전담 확대 작업자'로 대하면 기대가 어긋나지 않습니다.

할 수 있는 것

  • 기존 이미지를 받아 확대된 이미지를 출력하며, 표준적인 image-to-image 변환에 해당합니다.
  • 확대와 동시에 선명도 표현을 개선하며, 이것이 'crisp'라는 이름이 가리키는 방향입니다.
  • 파이프라인의 독립 단계로 반복 호출될 수 있고, 입출력이 모두 이미지라 추가적인 텍스트 상태를 도입하지 않습니다.
  • 동질적인 소재의 일괄 처리에 적합합니다. 예를 들어 특정 상품 이미지 묶음을 목표 크기로 일괄 올리는 경우입니다.

하지 않거나 할 수 없는 것

  • 텍스트 프롬프트로 이미지를 생성하지 않습니다. 텍스트-투-이미지 모델이 아니며 입력에 prompt라는 역할이 없습니다.
  • 화면 내용을 이해하지 않습니다. 대신 다시 그리거나, 스타일을 바꾸거나, 배경을 교체하거나, 누락된 피사체를 채워 넣지 않습니다. 이런 요구는 생성 또는 편집 계열 모델에 속합니다.
  • 없는 디테일을 창조하지 못합니다. 확대는 본질적으로 기존 픽셀에 기반한 추론이며, 원본이 심하게 흐리거나 압축 아티팩트가 매우 심하거나 피사체 자체 정보가 부족하면 확대 결과도 제한됩니다. 입력 품질이 출력의 상한을 결정합니다.
  • 확대 배율이나 목표 해상도를 지정할 수 없습니다. 현재 공개 파라미터는 필수인 이미지 공개 URL image_url뿐이며, 형식은 JPEG, PNG, WEBP를 지원하고 단일 파일은 10MB를 넘지 않습니다. 텍스트 프롬프트도, 배율이나 출력 크기 파라미터도 없습니다.

실용적인 판단: 잘 다듬은 샘플 이미지가 아니라 손에 있는 가장 나쁜 업무 소재 묶음으로 먼저 한 차례 시험하세요. 최악의 입력을 확대한 결과가 받아들일 수 없다면 문제는 대개 호출 측이 아니라 입력 측에 있습니다.

확대는 이미지 대 이미지입니다: 사진이 들어가고 더 큰 사진이 나옵니다. 취소선이 그어진 텍스트 블록은 텍스트-투-이미지를 하지 않는다는 것을 나타냅니다.

호출 전에 확인할 입력 및 출력 규격

HiAPI.ai 통합 인터페이스에 연동할 때 아래 체크리스트를 마친 뒤 업무 코드를 작성하면 대부분의 재작업을 줄일 수 있습니다.

입력 측

  • 파일이 정상적으로 디코딩되는지. 먼저 로컬에서 형식과 무결성을 검증하고, 손상된 파일은 보내지 마세요. 호출 횟수를 낭비하는 일입니다.
  • 파일이 입력 제약을 충족하는지. 공개 제약은 형식이 JPEG, PNG 또는 WEBP이고 단일 파일이 10MB를 넘지 않는 것입니다. 원본이 너무 작으면 확대 이득이 제한되고, 너무 크면 먼저 용량 초과 여부를 확인하세요.
  • 색상과 투명 채널. 공개 형식은 JPEG, PNG, WEBP입니다. 투명 채널이 있거나 이 목록에 없는 소스는 먼저 샘플로 출력이 기대에 맞는지 확인하세요.
  • 파일 용량. 큰 파일의 업로드 소요 시간과 타임아웃 설정이 맞아야 합니다. 기본의 짧은 타임아웃으로 큰 이미지를 처리하지 마세요.

출력 측

  • 출력 크기. 요청에서 목표 해상도를 지정할 수 없습니다. 연동 시 서로 다른 크기의 원본 이미지 몇 장으로 '원본 크기 → 출력 크기'의 실제 동작을 확인해 자신만의 대조표를 만드세요. 공개되지 않은 명명된 프리셋을 가정해 출력을 단정하지 마세요.
  • 출력 형식과 용량. 확대된 파일은 보통 더 큽니다. 다운스트림 저장과 대역폭을 미리 추정해야 합니다.
  • 선명도에 대한 주관적 검수 기준. '충분히 선명하다'의 정의를 미리 정해야 달성 여부를 판단할 수 있습니다.

파라미터 측

현재 공개 파라미터는 필수인 image_url뿐입니다. 배율, 목표 해상도, 프롬프트 또는 기타 공개되지 않은 파라미터를 임의로 추가하지 말고, 먼저 이 항목으로 최소 요청을 통과시키세요.

최소 검증 순서: 작은 이미지 한 장으로 통과 → 업무의 대표 이미지로 교체 → 최악 품질 이미지로 교체 → 최대 크기 이미지로 교체. 네 단계를 모두 통과한 뒤에 일괄 처리를 논하세요.

입력 검증, 요청 발송, 출력 확인으로 이어지는 점검 흐름을 직조 리본 사각형의 점진적 관계로 표현했습니다.

장당 과금: 단가 계산 방법

crisp-upscale의 과금 기준은 장당 과금입니다—성공한 호출 한 번이 이미지 한 장, 과금 한 번에 해당합니다. 가격은 한 단계뿐입니다: $0.004/장.

사용량 추정 방법

월 비용 ≈ 월 호출 장수 × $0.004. 실제로 관리해야 할 변수는 하나뿐입니다: 월 호출 장수. 이는 세 가지 요인의 곱으로 구해집니다:

  1. 일평균 처리하는 업무 객체 수;
  2. 객체별 평균 확대 필요 이미지 수;
  3. 재시도와 재작업으로 인한 추가 계수.

세 번째 항목이 가장 쉽게 간과됩니다. 실패 재시도, 품질 불만족으로 인한 재확대, 동일 이미지가 서로 다른 흐름에서 반복 처리되는 것이 모두 실제 장수를 업무 예상보다 높입니다. 이 세 항목을 각각 기록하면 비용을 호출량 기준으로 계산하고 관리할 수 있습니다.

호출량을 제어하는 몇 가지 수단

  • 중복 제거. 동일 이미지(콘텐츠 해시 기준 판단)는 한 번만 확대하고 결과를 저장해 재사용합니다. 콘텐츠 라이브러리에서 동일 소재가 여러 곳에서 참조되는 상황에서는 이 항목이 상당한 비율을 절약합니다.
  • 판단 후 확대. 원본 크기가 이미 표시 요구를 충족하면 확대할 필요가 없습니다. 크기 판단 한 단계만 추가해도 무효 호출을 막을 수 있습니다.
  • 일괄 처리와 비동기. 실시간이 아닌 시나리오는 큐를 사용해 확대를 사용자 요청 경로에서 분리합니다. 재시도를 합칠 수 있고 타임아웃으로 인한 중복 제출도 피할 수 있습니다.
  • 계층화 전략. 커버, 첫 화면 등 고가치 위치에는 확대를 적용하고 목록 썸네일은 원본을 직접 사용해 예산을 눈에 보이는 곳에 집중합니다.
  • 예산 가드레일. 일별 또는 주별 호출 상한을 설정하고 경고를 걸어 특정 루프 버그가 한도를 소진하는 것을 방지합니다—이런 사고는 장당 과금 모델에서 비용이 매우 직접적입니다.

먼저 전체 샘플 통계를 한 차례 수행한 뒤 무엇을 얼마나 확대할지 결정하는 것이 감으로 배율을 정하는 것보다 훨씬 신뢰할 수 있습니다.

대표 사용법과 파이프라인 조합

확대는 단독으로 존재하는 경우가 드물고 보통 파이프라인의 한 단계입니다. 다음은 임베드에 적합한 몇 가지 시나리오입니다.

소재 후처리

사용자 업로드 또는 운영 업로드 이미지를入库 전에 일괄적으로 확대를 거쳐 콘텐츠 라이브러리의 크기 기준선을 일치시킵니다. 그러면 프런트엔드가 이미지마다 개별 대응할 필요 없이 디자인 시안을 고정 크기로 만들 수 있습니다.

오래된 이미지와 저품질 이미지의 복원 체인

기존 콘텐츠의 스크린샷, 과도하게 압축된 삽화는 먼저 기본 정리(예: 자르기, 형식 통일)를 하고 crisp-upscale로 확대한 뒤 목표 크기에 맞춰 잘라 전달합니다. 순서에 주의하세요: 먼저 수리하고 나중에 확대, 복원 가능한 문제를 확대 전에 해결합니다.

생성 후 마무리

모든 이미지 생성 또는 편집 파이프라인의 끝에 확대 단계를 붙여 중간 크기 결과를 전달 크기로 올릴 수 있습니다. 이 체인의 장점은 결합 해제입니다—생성 모델을 교체하든 말든 확대 단계는 건드릴 필요가 없습니다.

파이프라인 구조

업로드 → 검증(형식, 크기, 해시 중복 제거) → 확대 호출 → 품질 샘플링 검사 → 저장 → CDN 배포. 품질 샘플링 검사는 사람이 표본을 보거나 상위 소재에만 자동 지표 모니터링을 적용할 수 있습니다. 어느 쪽이든 '기준 미달이면 반려'하는 출구를 마련해야 합니다.

엔지니어링 측면의 두 가지 알림: 확대 단계는 멱등이어야 하며(같은 입력 같은 출력, 결과 캐시 가능), 실패 시 독립적으로 재시도할 수 있어야 하며 전체 체인을 다시 실행하지 마세요.

흔한 함정과 검증 체크리스트

다음은 연동 과정에서 반복적으로 나타나는 문제이며, 대부분 출시 전에 한 번에 회피할 수 있습니다.

흔한 함정

  • 생성 모델로 사용하는 경우. 누락된 콘텐츠를 채우거나 화면을 바꾸기를 기대하면 결과는 반드시 실망스럽습니다. 능력 경계를 먼저 맞춰야 합니다.
  • 잘 다듬은 이미지로 검수하는 경우. 샘플 이미지는 예쁘지만 출시 후 온라인 저품질 소재를 만나면 무너집니다. 검수 샘플은 실제 업무 분포에서 나와야 합니다.
  • 타임아웃 설정이 너무 짧은 경우. 큰 이미지 처리는 더 오래 걸립니다. 기본 타임아웃은 '실제로는 성공했지만 클라이언트가 포기'하는 중복 과금을 쉽게 만듭니다.
  • 중복 제거가 없는 경우. 동일 소재가 반복 확대되어 청구서 증가가 업무 증가와 비례하지 않습니다.
  • 공개되지 않은 출력 프리셋을 가정하는 경우. 요청에서 출력 크기를 지정할 수 없습니다. 특정 명명된 해상도로 조판하면 다운스트림 전체를 다시 해야 할 수 있습니다.
  • 무제한 루프 재시도. 실패 시 즉시 재시도하고 상한을 두지 않으면 한 번의 장애로 하루치 예산을 태울 수 있습니다.

출시 전 검증 체크리스트

  1. 실제 업무 분포의 작은 샘플(최악 품질 이미지 포함)로 전체 체인을 통과시킵니다;
  2. 입력 규격과 출력 크기의 실제 동작을 기록하고 확인합니다;
  3. 호출마다 과금 대응 관계를 확인해 숨은 중복 호출이 없는지 점검합니다;
  4. 중복 제거 캐시 적중률을 검증합니다;
  5. 타임아웃, 재시도, 서킷 브레이커 정책을 검증합니다;
  6. 일상 예산 경고와 호출량 대시보드를 구축합니다;
  7. 소규모 트래픽 카나리를 한 차례 실시해 확대 전후의 주관적 화질과 다운스트림 지표를 비교한 뒤 전체 전환합니다.

확대의 이득은 점진적이고 위험도 점진적입니다: 소규모 샘플 비교 단계를 탄탄히 하면 이후 대규모 연동은 기본적으로 운영 작업입니다.

이미지 한 장으로 통과하는 것부터 시작해 규격, 과금, 중복 제거 세 가지를 정하면 crisp-upscale은 조용하지만 항상 일하는 이미지 파이프라인의 한 단계로 안정적으로 자리잡을 수 있습니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기