사용 가이드
recraft/crisp-upscale 시작 가이드: 이미지 확대 API의 연동 핵심과 과금
능력 경계부터 장당 과금까지, 개발자가 이미지 확대를 운영 흐름에 안정적으로 연동하는 방법
- 모델
- recraft-crisp-upscale
이 페이지에서
crisp-upscale이 해결하는 문제
이미 존재하지만 해상도가 부족한 이미지를 더 크고 가장자리가 더 선명한 버전으로 바꾸는 것—이것이 recraft/crisp-upscale의 역할입니다. 이 모델은 image-to-image(이미지 대 이미지) 카테고리에 속합니다. 이미지를 주면 확대된 이미지를 돌려줍니다. 입력에 텍스트 프롬프트 자리는 없고 출력 유형은 이미지로 고정됩니다.
이런 모델이 해결하는 문제는 매우 구체적입니다:
- 소재 크기가 제각각입니다. 사용자가 업로드한 이미지, 기존 콘텐츠 라이브러리의 이미지, 제3자 협력사가 제공한 이미지의 해상도가 들쭉날쭉한데 프런트엔드 표시 크기는 디자인 요구로 고정되어 있습니다.
- 오래된 콘텐츠를 재활용해야 합니다. 몇 년 전의 삽화, 스크린샷, 썸네일을 더 큰 컨테이너에 그대로 넣으면 흐려집니다.
- 생성 결과의 마무리. 모든 이미지 생성 또는 편집 파이프라인의 끝에는 최종 크기로 전달하기 위한 확대 단계가 필요할 수 있습니다.
필요가 '한 문장으로 이미지 한 장 생성하기'라면 이 모델의 범위가 아닙니다. 필요가 '이미지가 있는데 더 크고 선명하게 만들고 싶다'라면 여기에 해당합니다. 판단 기준은 간단합니다: 호출 전에 구체적인 이미지 파일이 이미 손에 있는가. 있다면 이 모델이고, 없다면 먼저 다른 곳에서 생성 문제를 해결해야 합니다.
개발자에게 이런 단일 책임은 오히려 좋은 일입니다: 인터페이스 의미가 단순하고 입출력 구조가 안정적이며 실패 원인을 더 쉽게 찾을 수 있습니다. 확대는 독립적으로 테스트하고 독립적으로 롤백할 수 있는 단계로, 프롬프트 엔지니어링과 얽히지 않습니다.

능력 경계: 무엇을 할 수 있고 무엇을 기대하지 말아야 하는가
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. 실제로 관리해야 할 변수는 하나뿐입니다: 월 호출 장수. 이는 세 가지 요인의 곱으로 구해집니다:
- 일평균 처리하는 업무 객체 수;
- 객체별 평균 확대 필요 이미지 수;
- 재시도와 재작업으로 인한 추가 계수.
세 번째 항목이 가장 쉽게 간과됩니다. 실패 재시도, 품질 불만족으로 인한 재확대, 동일 이미지가 서로 다른 흐름에서 반복 처리되는 것이 모두 실제 장수를 업무 예상보다 높입니다. 이 세 항목을 각각 기록하면 비용을 호출량 기준으로 계산하고 관리할 수 있습니다.
호출량을 제어하는 몇 가지 수단
- 중복 제거. 동일 이미지(콘텐츠 해시 기준 판단)는 한 번만 확대하고 결과를 저장해 재사용합니다. 콘텐츠 라이브러리에서 동일 소재가 여러 곳에서 참조되는 상황에서는 이 항목이 상당한 비율을 절약합니다.
- 판단 후 확대. 원본 크기가 이미 표시 요구를 충족하면 확대할 필요가 없습니다. 크기 판단 한 단계만 추가해도 무효 호출을 막을 수 있습니다.
- 일괄 처리와 비동기. 실시간이 아닌 시나리오는 큐를 사용해 확대를 사용자 요청 경로에서 분리합니다. 재시도를 합칠 수 있고 타임아웃으로 인한 중복 제출도 피할 수 있습니다.
- 계층화 전략. 커버, 첫 화면 등 고가치 위치에는 확대를 적용하고 목록 썸네일은 원본을 직접 사용해 예산을 눈에 보이는 곳에 집중합니다.
- 예산 가드레일. 일별 또는 주별 호출 상한을 설정하고 경고를 걸어 특정 루프 버그가 한도를 소진하는 것을 방지합니다—이런 사고는 장당 과금 모델에서 비용이 매우 직접적입니다.
먼저 전체 샘플 통계를 한 차례 수행한 뒤 무엇을 얼마나 확대할지 결정하는 것이 감으로 배율을 정하는 것보다 훨씬 신뢰할 수 있습니다.
대표 사용법과 파이프라인 조합
확대는 단독으로 존재하는 경우가 드물고 보통 파이프라인의 한 단계입니다. 다음은 임베드에 적합한 몇 가지 시나리오입니다.
소재 후처리
사용자 업로드 또는 운영 업로드 이미지를入库 전에 일괄적으로 확대를 거쳐 콘텐츠 라이브러리의 크기 기준선을 일치시킵니다. 그러면 프런트엔드가 이미지마다 개별 대응할 필요 없이 디자인 시안을 고정 크기로 만들 수 있습니다.
오래된 이미지와 저품질 이미지의 복원 체인
기존 콘텐츠의 스크린샷, 과도하게 압축된 삽화는 먼저 기본 정리(예: 자르기, 형식 통일)를 하고 crisp-upscale로 확대한 뒤 목표 크기에 맞춰 잘라 전달합니다. 순서에 주의하세요: 먼저 수리하고 나중에 확대, 복원 가능한 문제를 확대 전에 해결합니다.
생성 후 마무리
모든 이미지 생성 또는 편집 파이프라인의 끝에 확대 단계를 붙여 중간 크기 결과를 전달 크기로 올릴 수 있습니다. 이 체인의 장점은 결합 해제입니다—생성 모델을 교체하든 말든 확대 단계는 건드릴 필요가 없습니다.
파이프라인 구조
업로드 → 검증(형식, 크기, 해시 중복 제거) → 확대 호출 → 품질 샘플링 검사 → 저장 → CDN 배포. 품질 샘플링 검사는 사람이 표본을 보거나 상위 소재에만 자동 지표 모니터링을 적용할 수 있습니다. 어느 쪽이든 '기준 미달이면 반려'하는 출구를 마련해야 합니다.
엔지니어링 측면의 두 가지 알림: 확대 단계는 멱등이어야 하며(같은 입력 같은 출력, 결과 캐시 가능), 실패 시 독립적으로 재시도할 수 있어야 하며 전체 체인을 다시 실행하지 마세요.
흔한 함정과 검증 체크리스트
다음은 연동 과정에서 반복적으로 나타나는 문제이며, 대부분 출시 전에 한 번에 회피할 수 있습니다.
흔한 함정
- 생성 모델로 사용하는 경우. 누락된 콘텐츠를 채우거나 화면을 바꾸기를 기대하면 결과는 반드시 실망스럽습니다. 능력 경계를 먼저 맞춰야 합니다.
- 잘 다듬은 이미지로 검수하는 경우. 샘플 이미지는 예쁘지만 출시 후 온라인 저품질 소재를 만나면 무너집니다. 검수 샘플은 실제 업무 분포에서 나와야 합니다.
- 타임아웃 설정이 너무 짧은 경우. 큰 이미지 처리는 더 오래 걸립니다. 기본 타임아웃은 '실제로는 성공했지만 클라이언트가 포기'하는 중복 과금을 쉽게 만듭니다.
- 중복 제거가 없는 경우. 동일 소재가 반복 확대되어 청구서 증가가 업무 증가와 비례하지 않습니다.
- 공개되지 않은 출력 프리셋을 가정하는 경우. 요청에서 출력 크기를 지정할 수 없습니다. 특정 명명된 해상도로 조판하면 다운스트림 전체를 다시 해야 할 수 있습니다.
- 무제한 루프 재시도. 실패 시 즉시 재시도하고 상한을 두지 않으면 한 번의 장애로 하루치 예산을 태울 수 있습니다.
출시 전 검증 체크리스트
- 실제 업무 분포의 작은 샘플(최악 품질 이미지 포함)로 전체 체인을 통과시킵니다;
- 입력 규격과 출력 크기의 실제 동작을 기록하고 확인합니다;
- 호출마다 과금 대응 관계를 확인해 숨은 중복 호출이 없는지 점검합니다;
- 중복 제거 캐시 적중률을 검증합니다;
- 타임아웃, 재시도, 서킷 브레이커 정책을 검증합니다;
- 일상 예산 경고와 호출량 대시보드를 구축합니다;
- 소규모 트래픽 카나리를 한 차례 실시해 확대 전후의 주관적 화질과 다운스트림 지표를 비교한 뒤 전체 전환합니다.
확대의 이득은 점진적이고 위험도 점진적입니다: 소규모 샘플 비교 단계를 탄탄히 하면 이후 대규모 연동은 기본적으로 운영 작업입니다.
이미지 한 장으로 통과하는 것부터 시작해 규격, 과금, 중복 제거 세 가지를 정하면 crisp-upscale은 조용하지만 항상 일하는 이미지 파이프라인의 한 단계로 안정적으로 자리잡을 수 있습니다.