블로그

사용 가이드

HiAPI API로 qwen-image-2.1-turbo를 사용한 이커머스 제품 이미지 생성

개발자를 위한 빠른 카탈로그 비주얼 워크플로: 투명 PNG 출력과 실행 가능한 API 요청

Nov 20, 2026
테라코타와 엄버 색상의 넓은 가로 계단형 띠가 기압계 그래프처럼 내려가는 따뜻한 모래빛 톤의 표지 그래픽.
이 페이지에서

qwen-image-2.1-turbo가 적합한 상황

상품 카탈로그의 이미지 작업은 겉보기에는 창의적인 문제이지만 실질적으로는 처리량 문제입니다. 단일 대표 이미지는 수작업으로 정교하게 다듬을 수 있지만, 수천 개의 SKU를 보유한 매장에는 일관된 구도, 예측 가능한 리드 타임, 그리고 기존 자산 파이프라인에 바로 연결되는 출력이 필요합니다. 어떤 이미지 모델을 선택하느냐에 따라 파이프라인을 얼마나 다시 구축해야 하는지가 결정됩니다.

일반적으로 이 결정을 좌우하는 세 가지 기준이 있습니다:

  • 부하 상황에서의 지연 시간. 야간 카탈로그 작업은 배치 작업입니다. 대화형 시나리오에서 좋은 성능을 내는 모델도 10,000개 SKU의 갱신을 괴롭게 만들 수 있습니다.
  • 출력 형식 적합성. 합성 단계에서 알파 채널이 필요한데 모델이 불투명 이미지만 반환한다면, 분할 단계를 직접 추가해야 합니다.
  • 제품 설명 언어에 대한 프롬프트 성능. 제품 프롬프트는 짧고 구체적이며 반복적입니다. 이런 프롬프트를 안정적으로 처리하는 모델이 개방형 아트 프롬프트에서 뛰어난 모델보다 낫습니다.

이 가이드는 처음 두 기준과 이 둘을 연결하는 요청 패턴에 초점을 맞춥니다. turbo 변형이 제품 이미지 파이프라인에서 어디에 위치하는지, 투명 PNG 출력이 후처리 체인을 어떻게 바꾸는지 살펴보고, 워커에 바로 넣을 수 있는 요청을 제시합니다. 마지막으로 일괄 확장 시 주의할 점을 논의하고, 텍스트 기반 생성이 적합하지 않을 때 이미지-투-이미지 방식을 간략히 비교합니다.

제품 이미지 작업이 모델 선택 기준으로 분기되는 모습을 분기하는 계단형 띠로 표현.

투명 PNG 출력과 후처리 체인

제품 이미지 파이프라인은 네 단계로 볼 수 있습니다: 요청 구성 → 생성 → 출력 처리 → 게시. turbo 변형은 의도적인 선택입니다. 두 번째 단계를 카탈로그 규모를 지탱할 만큼 빠르고 저렴하게 만들어, 엔지니어링 예산을 첫 번째와 세 번째 단계에 쓸 수 있게 하는 것입니다.

올바른 첫 선택이 되는 경우

다음의 경우 qwen-image-2.1-turbo를 선택하세요:

  • 프롬프트가 구조화되고 반복 가능한 경우 — 카테고리마다 템플릿 하나씩, 소재, 색상, 각도, 배경 의도에 대한 슬롯을 둡니다.
  • 세심하게 아트 디렉션된 한 장의 이미지보다 SKU마다 많은 변형(각도, 배색, 장면)을 생성해야 하는 경우.
  • 다운스트림 합성이 이미 자동화되어 있어, 완성된 장면보다 깔끔한 누끼가 더 가치 있는 경우.
  • 참조 이미지를 도입하기 전에 텍스트 기반 기준선을 먼저 확보하려는 경우.

더 강력한 모델이 필요한 경우

특정 SKU가 참조 사진과 엄격히 일치해야 하는 매우 특수한 구도를 요구하거나, 병목이 수량이 아니라 복잡한 장면에서의 출력 품질이라면 turbo 계층은 적절한 기본 선택이 아닙니다. 이 경우 대부분의 카탈로그 변형은 turbo로 처리하고 소량의 대표 이미지 자산은 더 무거운 생성 경로에 맡기세요. 파이프라인 형태는 그대로 두고 모델 식별자만 교체하면 됩니다.

교체 가능한 모델 슬롯 설계

turbo 계층이 규모를 겨냥하는 만큼, 모델 이름은 코드베이스 곳곳에 하드코딩된 상수가 아니라 구성으로 취급해야 합니다. 워커 시작 시 IMAGE_MODEL 환경 변수를 읽으면 요청 코드를 바꾸지 않고도 일부 카테고리에서 다른 모델을 A/B 테스트할 수 있습니다. 이 결정 덕분에 이 가이드의 나머지 내용이 이식성을 갖습니다.

4단계 띠 파이프라인에서 turbo 변형은 압축되어 들어 올려진 계단으로 표현됨: 연결, 생성 가속, 출력 처리, 게시.

실행 가능한 HiAPI 제품 이미지 요청

투명 PNG는 카탈로그 파이프라인에서 가장 레버리지가 큰 출력 선택입니다. 비용이 많이 드는 단계인 '제품을 배경에서 분리하기'를 생성 단계로 앞당기기 때문입니다. 불투명 렌더링을 분할하는 대신 알파 채널이 있는 자산을 받아 직접 합성하면 됩니다.

다운스트림에서 달라지는 점

알파 채널이 있으면 배경은 모델링 영역이 아니라 렌더링 영역의 관심사가 됩니다. 같은 누끼를 흰색 스튜디오 배경에 올려 PDP 대표 이미지로, 라이프스타일 장면에 올려 마케팅 슬롯으로, 브랜드 단색 배경에 올려 카테고리 타일로 사용할 수 있습니다. 모두 한 번의 생성에서 나옵니다. 이것이 핵심 경제성입니다: 제품 자산 하나, 게시 변형 여럿.

실제 운영에서는 다음 단계를 계획하세요:

  • 알파 채널 검증. 이미지에 실제로 의미 있는 알파 채널이 있는지, 피사체가 화면 가장자리에서 잘리지 않았는지 확인합니다. 누끼가 테두리에 닿는 것은 합성 문제가 아니라 생성 실패입니다.
  • 캔버스 정규화. 합성 전에 일관된 캔버스에서 누끼의 크기를 조정하고 채워, SKU마다 위치가 예측 가능하게 만듭니다.
  • 게시 위치별 합성. 배경 프리셋(크기, 색상, 선택적 배경 자산)을 데이터로 저장하고 동일한 원본 PNG에서 각 게시 위치를 렌더링합니다.
  • 원본 저장, 렌더 결과 게시. 투명 원본을 규범 자산으로 영구 저장하고, 각 합성 변형은 재생성 가능한 파생물로 취급합니다.

파일 크기 트레이드오프에 주의하세요. 알파 채널은 PNG를 더 크게 만들고, 카탈로그 저장소는 여기에 변형 수를 곱합니다. CDN이 WebP나 AVIF를 제공한다면 게시 시 변환하되 PNG 원본은 보관하세요.

투명 누끼를 떠 있는 레이어로 표현: 동일한 실루엣이 각 배경 변형 위에 겹쳐지고 오른쪽으로 저장 단계로 흘러감.

일괄 작업으로 확장하고 통합 함정 피하기

아래의 모든 내용은 HiAPI 통합 인터페이스 위에서 실행됩니다. 기본 URL 하나, 자격 증명 하나, 모델 간 일관된 요청 형태를 사용합니다. 스키마를 확정하기 전에 qwen-image-2.1-turbo 모델 페이지에서 정확한 매개변수 목록과 현재 필드명을 확인하세요. 여기서 중요한 것은 패턴 자체입니다.

요청 형태

제품 이미지 호출은 프롬프트와 출력 사양으로 구성됩니다. 템플릿으로 프롬프트를 구성해 SKU마다 변수만 제공하도록 하세요:

import os, requests

HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")

def product_prompt(sku):
    return (
        f"studio product photo of {sku['name']}, {sku['material']}, "
        f"{sku['color']} finish, three-quarter view, soft even lighting, "
        "centered on a plain background, no text, no props"
    )

def generate(sku):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {HIAPI_KEY}"},
        json={
            "model": MODEL,
            "prompt": product_prompt(sku),
            "transparent_background": True,
            "n": 1,
        },
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()

요청 본문에 대해 두 가지 유의점이 있습니다. 첫째, 투명 배경을 명시적으로 요청하세요. 이는 호출의 매개변수이지 다운로드 후 추론할 대상이 아닙니다. 둘째, 호출마다 n을 낮게 유지하고 작업 단위에서 병렬화하세요. 단일 이미지 요청 20개를 배치하는 편이 이미지 20장을 한 번에 요청하는 것보다 재시도가 훨씬 깔끔합니다. 후자는 한 장만 실패해도 그룹 전체를 잃기 때문입니다.

응답을 방어적으로 처리하기

응답에는 이미지 데이터가 담겨 있습니다(보낸 매개변수에 따라 URL 또는 인코딩된 페이로드). 가져오기를 생성과 별개의 장애 영역으로 취급하세요. 생성이 반환된 후 다운로드하고, 검증하고, 자체 스토리지에 업로드합니다. 그때부터 파이프라인은 임시 결과가 아니라 자체 버킷을 참조합니다. 이것이 재시도와 재렌더링을 관리 가능하게 만드는 핵심입니다.

이미지-투-이미지 경로와 비교

실행 가능한 스크립트와 실행 가능한 카탈로그 작업 사이의 격차는 거의 항상 지루한 부분에서 발생합니다.

프롬프트를 데이터로 템플릿화하기

프롬프트 조각을 코드가 아니라 카테고리별 구성 파일에 두세요. 각 SKU는 슬롯을 제공하고, 카테고리는 문장 프레임과 부정 제약("no text, no watermarks, no props")을 제공합니다. 특정 카테고리의 구도가 잘못되면 수천 행의 데이터가 아니라 템플릿 하나만 고치면 됩니다.

의도적으로 재시도하기

재시도 가능한 실패(타임아웃, 일시적 서버 오류, 속도 제한)를 최종 실패(잘못된 매개변수, 거부된 프롬프트)와 구분하세요. 첫 번째는 지수 백오프와 재시도 상한으로 재시도하고, 두 번째는 즉시 실패로 처리해 원인을 드러내세요. 잘못된 형식의 요청을 재시도하는 것은 큐만 소모할 뿐입니다. 여기서 멱등성이 중요합니다. SKU와 프롬프트 해시를 각 작업의 키로 사용해 재시도된 작업이 중복되지 않고 덮어쓰도록 하세요.

스토어에 노출되기 전에 검증하기

생성과 게시 사이에 검증 관문을 두세요. 저비용 자동 검사로 대부분의 불량 출력을 잡을 수 있습니다:

  • 알파 채널이 존재하고 피사체가 가장자리에서 잘리지 않았는지.
  • 해상도가 게시하는 최대 위치의 최소 요구 사항을 충족하는지.
  • 현재 자산과 지각 해시를 비교해 의도치 않은 근사 중복을 표시.

관문을 통과하지 못한 콘텐츠는 즉시 폐기하지 말고 검토 큐로 보내세요. 조용한 실패야말로 카탈로그가 색상이 잘못된 제품으로 조용히 채워지는 방식입니다.

동시성 한도에 주의하기

배치 작업은 속도 제한에 점진적으로 닿기보다 돌발적으로 닿는 경우가 많습니다. 워커 동시성을 생각하는 한도보다 낮게 설정하고, 그 한도를 구성 가능하게 하며, 큐가 백로그를 흡수하도록 하세요. 제한에 걸리더라도 완료되는 파이프라인이 왔다 갔다 진동하는 파이프라인보다 낫습니다.

요청이 아니라 출력으로 예산 책정하기

과금은 생성한 출력에 따르므로, SKU당 생성하는 자산 수를 비용 신호로 추적하세요. 특정 카테고리가 제품당 많은 변형을 생성하기 시작한다면, 청구서에서 발견할 일이 아니라 프롬프트 설계에서 의도적으로 내려야 할 결정입니다.

이미지-투-이미지 경로와 비교

제품에 사용할 사진이 아직 없을 때 — 새 SKU가 아직 촬영되지 않았거나, 제품에 아직 촬영된 적 없는 새 색상이 있거나, 게시용 임시 자산이 필요할 때 — 텍스트 기반 생성이 올바른 기본 선택입니다. 프롬프트가 결과를 완전히 설명하고, 투명 출력이 분할 단계 없이 합성 가능한 자산을 제공합니다.

이미지-투-이미지 경로는 입력을 뒤집습니다. 참조 이미지를 제공하면 모델이 그 위에서 작업하며, 실제 제품에 대한 충실도가 타협 불가일 때 필요한 방식입니다. 실제 스티치, 실제 하드웨어 마감, 고객이 받게 될 정확한 색조를 맞추는 것입니다. 이 모드에서 참조 이미지는 생성을 정직하게 유지하는 제약입니다.

대부분의 카탈로그에 실용적인 구분:

  • Turbo 텍스트-투-이미지는 규모용 — 변형, 배경, 카테고리 타일, 초기 등록용 임시 이미지.
  • 이미지-투-이미지는 고객이 구매 결정에 사용하며 시각적 정확성이 중요한 모든 경우.

둘은 같은 파이프라인 골격을 공유하므로 전환은 재작성이 아니라 모델 식별자와 입력 필드 하나를 바꾸는 일입니다. 참조 이미지 기반 출력이 필요할 때 qwen-image-3.0 이미지-투-이미지 모델을 같은 워커에 연결하고 프롬프트 옆에 참조 이미지를 첨부하면 됩니다.

먼저 한 카테고리에서 turbo 경로를 실행해 검증 통과율을 측정한 뒤 점진적으로 확장하세요. 모델 페이지에 연결해야 할 필드가 나열되어 있습니다.

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

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

API 문서 보기