qwen-image-2.1-pro로 이커머스 제품 이미지 생성하기: API 사용법과 프롬프트 레시피

이커머스 제품 이미지에 qwen-image-2.1-pro를 선택할 만한 이유

이커머스 이미지 작업은 한 가지만 하는 경우가 드뭅니다. 신규 SKU를 위한 카탈로그 촬영, 마켓플레이스 상품 페이지용 누끼 이미지, 랜딩 페이지용 라이프스타일 컷, 그리고 프로모션 코너 배지가 붙은 배너까지—보통 이 모든 것을 같은 주 안에 납품해야 합니다. qwen-image-2.1-pro를 평가할 만한 지점은 바로 여기에 있습니다. 워크플로우가 동일한 제품 데이터에서 위의 모든 결과물을 만들어내야 할 때, 전문화된 도구들을 줄줄이 연결하는 대신 하나의 모델 안에서 생성, 기존 자산 편집, 투명 PNG 출력, 이미지 내 텍스트 렌더링을 모두 처리할 수 있기 때문입니다.

세 가지 작업 유형이 대부분의 업무량을 커버합니다:

• 투명 누끼 — 제품이 투명 배경 위에 깔끔하게 분리되어 CMS의 어느 위치에든 바로 배치할 수 있습니다.
• 장면 합성 — 제품이 그럴듯한 라이프스타일 또는 스튜디오 환경에 배치되며, 텍스트 설명과 참조 이미지로 생성됩니다.
• 텍스트가 포함된 레이아웃 — 라벨, 코너 배지, 배너로서 텍스트가 선명하게 읽히고 올바른 위치에 있어야 합니다.

스튜디오를 대체할 수 없는 영역: 엄격한 브랜드 조명 요구사항이 있는 메인 비주얼, 그리고 제품 형상이 규제를 받는 모든 자산(예: 규제 대상 포장). 생성을 커버리지를 넓히고 반복 속도를 높이는 수단으로 보고, 인간 승인 관문은 유지하세요—이 가이드 뒤에 나오는 검수 프로세스가 바로 그 용도입니다.

실질적으로 조기에 결정해야 할 이유는 프롬프트 아키텍처입니다. 같은 모델이 누끼, 장면, 텍스트 레이아웃 모두를 담당한다는 것을 처음부터 안다면, 매 요청마다 즉석에서 프롬프트를 쓰는 대신 버전이 지정된 소규모 프롬프트 템플릿 세트를 구축할 수 있습니다. 이 결정은 초기에 비용이 들지 않지만 나중에 재작업을 피할 수 있습니다.

실행 가능한 요청: curl과 Python

프롬프트를 설계하기 전에, 먼저 이미지 한 장을 성공적으로 받아오세요. HiAPI의 각 모델은 일관된 요청 형태를 가집니다: API 키 하나, 모델명 하나, 그리고 요청 본문의 입력 파라미터.qwen-image-2.1-pro에 필요한 최소 파라미터는 프롬프트이며, 작업이 완전한 새 생성이 아니라 편집인 경우 편집할 입력 이미지를 추가로 지정합니다.

curl

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "무광 검정 세라믹 커피 머그의 스튜디오 제품 사진, 4분의 3 각도, 왼쪽에서 비추는 부드러운 확산 키 라이트, 연한 회색 이음새 없는 배경에 은은한 반사, 텍스트 없음",
    "size": "1024x1024"
  }'

Python requests

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-2.1-pro",
        "prompt": "무광 검정 세라믹 커피 머그의 스튜디오 제품 사진, "
                  "4분의 3 각도, 왼쪽에서 비추는 부드러운 확산 키 라이트, "
                  "연한 회색 이음새 없는 배경에 은은한 반사, 텍스트 없음",
        "size": "1024x1024",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

이 단계에서 두 가지 습관을 들일 만합니다. 첫째, API 키는 환경 변수에서 읽고 절대 하드코딩하지 마세요—곧 배치 작업에서 이를 실행하게 될 것입니다. 둘째, 로깅할 때 엔드포인트가 반환하는 사용량 필드를 포함해 전체 응답 본문을 보존하세요. 이것이 나중에 "승인된 자산당 비용"을 추측이 아니라 측정으로 판단할 근거가 됩니다.

먼저 위와 같은 범용 프롬프트로 요청을 한 번 실행하세요. 이미지를 받았고 응답 구조가 다운스트림 코드의 기대와 일치하는지 확인하세요. 그다음에야 레시피로 넘어가세요—프롬프트 설계는 시간이 걸리는 작업이므로, 중간에 파이프라인 문제를 발견하고 싶지는 않을 것입니다.

투명 PNG와 제품 장면을 위한 프롬프트 레시피

즉석 프롬프트는 쉽게 흔들립니다. 카탈로그 팀은 명시적 변수 슬롯이 있는 소규모 템플릿 세트를 API를 호출하는 코드와 함께 저장소에서 버전 관리하고, SKU별로 슬롯만 바꿔 끼우는 방식으로 일관된 결과를 얻습니다.

레시피 1: 투명 누끼

{product_name}의 제품 누끼, {distinguishing_detail}, 투명 배경 위에 완전히 분리됨.
{view_angle} 각도, 제품이 중앙에 완전히 프레임 안에 들어오며 사방에 약간의 여백.
부드럽고 균일한 스튜디오 조명, 배경에 하드 섀도 없음, 제품 바로 아래에만 약한 접촉 그림자.
사진처럼 사실적, 가장자리 선명, 텍스트 없음, 소품 없음, 배경 요소 없음.

슬롯: {product_name}("무광 검정 세라믹 커피 머그"), {distinguishing_detail}("눈에 띄는 테두리 두께와 작은 손잡이"), {view_angle}("4분의 3", "정면", "위에서 내려다본"). 투명 조항과 "배경에 그림자를 드리우지 않음" 조항은 그대로 유지하세요. 이 두 줄이 누끼 작업에서 대부분의 일을 합니다.

레시피 2: 라이프스타일 장면

{scene_description} 속 {product_name}의 라이프스타일 제품 사진.
제품이 주인공: 초점 선명, 비율 정확, {brand_color_note}.
{lighting_note}. 얕은 심도, 배경은 부드럽게 흐려짐.
자연스럽고 에디토리얼한 스타일. 텍스트 없음, 로고 없음, 배경에 보이는 브랜드 표시 없음.

슬롯: {scene_description}("린넨 냅킨과 아침 햇살이 들어오는 창가가 있는 밝고 미니멀한 주방 조리대"), {brand_color_note}("색상 변경 없음, 색조 편향 없음"), {lighting_note}("오른쪽에서 들어오는 따뜻한 방향성 아침 햇살").

레시피 3: 스튜디오 메인 비주얼

{product_name}의 스튜디오 제품 사진, {view_angle} 각도.
{background_description}. {key_light_direction}에서 비추는 키 라이트, 부드러운 필 라이트, 통제된 반사.
사진처럼 사실적, 재질과 표면 질감의 디테일 풍부. 텍스트 없음.

템플릿 라이브러리를 건강하게 유지하는 두 가지 규칙. 템플릿을 스크립트에서 직접 수정하지 마세요—템플릿 파일을 수정하고, 버전 번호를 올리고, 다시 생성하세요. 그리고 승인된 각 자산이 어느 레시피 버전에서 나왔는지 기록하세요. 그래야 템플릿이 변경되었을 때 이전 승인이 여전히 유효한지 판단할 수 있습니다.

기존 제품 이미지 편집

편집 요청은 대부분의 품질 문제가 발생하는 지점입니다. 모호한 프롬프트는 모델이 제품을 수정하는 대신 주변 장면을 재생성하게 만들기 때문입니다. 모든 편집 프롬프트를 명확히 세 부분으로 나누세요:

1. 무엇을 바꿀지 — 장면, 배경, 조명 또는 추가할 소품.
2. 무엇을 유지할지 — 제품의 형태, 비율, 라벨 패턴, 재질, 색상.
3. 무엇을 피할지 — 새로운 텍스트, 새로운 로고, 왜곡된 기하학, 중복된 부품.

사용 가능한 템플릿:

이 제품 사진을 편집하세요.
변경: 배경을 {new_background}으로 교체; 조명을 {new_lighting}으로 조정.
유지: 제품의 정확한 형태, 비율, 표면 재질, 모든 라벨 패턴을 완전히 그대로 유지.
금지: 텍스트 추가, 로고 추가, 제품 색상 변경, 기하학적 형태 변경.
사진처럼 사실적인 결과, 연속 촬영한 사진처럼 보이게.

예시 입력: {new_background} = "깔끔한 따뜻한 회색 이음새 없는 배경", {new_lighting} = "부드러운 상단 확산광, 제품 뒤쪽에 부드러운 그라데이션".

유지 조항은 보장이 아닙니다. 긴 편집—하나의 프롬프트에 배경 교체, 조명 조정, 소품 추가를 동시에 하는 것—은 모델이 제품 자체에서 흔들릴 여지를 더 줍니다. 나눠서 하세요: 먼저 배경 교체를 하고, 검수한 뒤, 승인된 중간 결과 위에 후속 편집을 얹어 부수적 변경을 적용하세요. 각 단계는 검수자가 실제로 판단할 수 있는 하나의 비교입니다.

동시에 SKU별로 표준 참조 이미지를 한 장 보관하세요. 검수자가 제품이 변경되었는지 확신하지 못할 때, 기준 진실은 마지막 생성 결과가 아니라 참조 이미지입니다.

텍스트 렌더링과 레이아웃 제어

이미지 내 텍스트는 즉석 프롬프트로 인해 가장 실망하기 쉬운 기능입니다. 최종 자산에 반드시 등장해야 하는 텍스트는 따옴표로 감싸고, 위치를 지정하고, 제약을 추가해야 합니다.

{product_name}의 이커머스 배너.
레이아웃: 제품은 오른쪽 3분의 1에, 텍스트 블록은 왼쪽 3분의 2에, 충분한 여백을 둠.
텍스트: 굵은 산세리프 폰트로 "{headline}"을 메인 제목으로 정확히 렌더링하고, 그 아래에 더 가벼운 굵기로 "{subline}"을 정확히 렌더링.
스타일: {color_scheme}, 깔끔하고 현대적, 가독성을 위한 높은 대비.
이미지의 다른 어떤 위치에도 텍스트 금지. 모든 단어는 적힌 대로 정확히 철자할 것.

각 줄이 왜 중요한가:

• 따옴표로 감싼 텍스트와 명시적인 "정확히" 지시는 패러프레이즈와 없는 단어 생성을 줄입니다.
• 위치와 비율("오른쪽 3분의 1", "왼쪽 3분의 2")은 모델이 제품을 제목 아래 묻히게 하는 것을 막습니다.
• "이미지의 다른 어떤 위치에도 텍스트 금지"는 흔한 실패 모드인 모서리에 그럴듯한 채움 텍스트가 나타나는 것을 억제하는 조항입니다.
• 짧은 제목 하나와 짧은 부제 하나가 문단보다 훨씬 신뢰할 만합니다. 레이아웃에 문단 카피가 필요하다면, 먼저 해당 카피 없이 이미지를 생성하고 CMS나 디자인 도구에서 카피를 조판하세요.

코너 배지와 라벨("New" 표시, 사이즈 표시)은 메인 비주얼에 덧붙이지 말고 각각의 작은 프롬프트로 처리하세요—따옴표로 감싼 단어 하나가 포함된 작은 배지 프롬프트는 검수 시 전체 배너보다 훨씬 검증하기 쉽습니다. 승인 전 반드시 전체 해상도에서 철자를 확인하세요. 텍스트 오류는 발견 비용은 낮지만 출시 후 대가는 큽니다.

출력 검수: 비교와 승인 루프

생성 자산은 인간 검토 없이 스토어에 게시되어서는 안 됩니다. 가장 비용이 낮고 신뢰할 수 있는 루프는 자산별 전후 비교입니다. 입력 사진(또는 완전 새 생성일 경우 사양 설명)을 생성 출력 옆에 두고, 프롬프트 레시피 버전과 변수 값을 기록하세요.

소규모 팀에 적합한 실행 가능한 루프:

1. 작은 배치를 생성하세요—전체 카탈로그가 아니라 SKU당 몇 개의 변형.
2. 나란히 비교 표를 렌더링: 왼쪽은 소스 이미지, 오른쪽은 후보 이미지, 아래에 프롬프트 기록.
3. 짧고 고정된 체크리스트로 검수: 제품 형태 변경 없음, 라벨 패턴 온전함, 배경 깔끔함, 텍스트 철자 정확, 여백 충분.
4. 각 후보를 통과 또는 거부로 표시하고, 통과 결과를 낳은 레시피 버전을 기록.
5. 그다음에야 전체 배치로 확장하고 승인된 레시피를 재사용. 승인 후 레시피가 변경되면 재검사 전까지 기존 승인을 임시 유효로 취급.

체크리스트는 짧게 유지하고 매번 똑같이 만드세요. 항상 일관된 네 항목 체크리스트가 불균일하게 시행되는 긴 양식보다 문제를 더 잘 찾아냅니다. 거부된 후보도 보관하세요—그것은 어떤 레시피 버전이 왜 폐기되었는지에 대한 증거이며, 다음 사람이 같은 실패를 재발견하지 않게 합니다.

이 루프는 비용 관리 수단이기도 합니다. 승인이 레시피에 묶여 있으므로, 승인된 자산 하나당 몇 번의 생성이 필요한지 계산할 수 있고, 시도 횟수를 가장 많이 소모한 템플릿을 대상으로 반복 개선할 수 있습니다.

비용, 지연 시간, 배치 처리 고려사항

가정이 아니라 자신의 측정값으로 계획하세요. HiAPI의 이미지 모델은 출력 이미지 기준으로 과금되므로, 지출을 좌우하는 변수는 "승인된 자산당 시도 횟수"입니다—이는 전적으로 프롬프트 품질과 검수 엄격성에 달려 있습니다. 현재 이미지당 가격은 웹사이트 가격 페이지에 있으니, 숫자를 코드나 예산 문서에 하드코딩하지 마세요.

합리적인 작업 방법:

• 베이스라인 측정. 승인된 레시피로 SKU 10개를 돌리고, 총 생성 횟수와 총 승인 수를 세어 승인된 자산당 시도 횟수를 도출하세요. 이 비율이 어떤 벤치마크보다도 문제를 잘 드러냅니다.
• 하나는 반복, 승인되면 배치. 프롬프트 반복은 한 번에 이미지 한 장으로. 레시피가 승인되면 적절한 동시성으로 배치 처리하고, 실패를 조용히 재과금하는 대신 기록하는 재시도 전략을 쓰세요.
• 지연 시간을 스케줄링 파라미터로 취급. 이미지 생성은 밀리초가 아니라 초 단위입니다. 작업을 비동기로 시작하고 결과를 큐에 넣어 검수자가 각 호출에서 블로킹하지 않고 큐에서 처리하게 하세요.
• 단가가 아니라 비율로 예산을 책정. 승인된 자산당 시도 횟수를 손에 쥐면, 카탈로그 추정은 자신의 측정값에 기반한 간단한 산수가 됩니다.

마지막 위생 습관: 레시피에 버전을 부여하고 매 요청에 레시피 버전을 기록하세요. 필드 하나만 추가하면 되지만, "왜 지난달에 이 자산이 다르게 보였지?"를 조사에서 단순 쿼리로 바꿔줍니다.

API로 누끼, 장면, 텍스트 레이아웃을 실행할 수 있는 최소 워크플로우를 구축하고, 프롬프트 라이브러리를 버전 관리하며, 무엇이 출시될 수 있는지는 기대가 아니라 검수 루프가 결정하게 하세요.