Qwen Image 2.1 Pro API는 어떻게 사용하나요? 5분 만에 텍스트→이미지와 이미지 편집 실행하기

TL;DR

• 무엇인가: Qwen Image 2.1 Pro가 HiAPI에 출시되었습니다. 모델 페이지를 열어 프롬프트를 작성하면 텍스트→이미지, 참조 이미지를 넣으면 편집입니다. 하나의 모델 ID로 최대 10장의 참조 이미지를 받을 수 있고, 다섯 가지 2K급 화면 비율을 지원하며 prompt_extend는 기본으로 켜져 있습니다. 신규 사용자 가입 시 200 크레딧을 드립니다.
• 얼마인가: 1장당 $0.05(100 크레딧)이며 성공적으로 생성된 이미지 기준으로 과금되고, 화면 비율과 무관하며 실패 시 환불되고 참조 이미지에는 추가 요금이 없습니다. $10으로 약 200장입니다. Turbo는 동일한 계약에 장당 $0.02입니다.
• 가장 빠른 호출 방법: 모델 페이지에서 프롬프트를 작성해 바로 실행하거나, 제품에 연동할 때는 POST https://api.hiapi.ai/v1/tasks를 사용하고 model에 qwen-image-2.1-pro를 입력합니다.

Qwen Image 2.1 Pro는 무엇인가? 2.0보다 새로운 점

텍스트→이미지와 편집이 같은 모델 ID를 공유합니다. image_urls를 전달하지 않으면 새 이미지를 생성하고, 전달하면 참조 이미지에 따라 편집하며 인터페이스를 전환할 필요가 없습니다.

2.0과 비교한 네 가지 차이점(2.0은 size로 픽셀을 자유롭게 지정했지만, 2.1은 화면 비율 값으로 변경):

• 하나의 ID로 두 가지 작업을 커버. 텍스트→이미지와 편집이 공유하며 요청은 image_urls만 다릅니다.
• 최대 10장의 참조 이미지. 제품 이미지와 장면 이미지를 한 번에 제출할 수 있으며 「图1」「图2」로 지칭합니다.
• 다섯 가지 2K급 화면 비율. 1:1 2048×2048, 16:9 2688×1536, 9:16 1536×2688, 4:3 2368×1728, 3:4 1728×2368이며 resolution 필드는 없습니다.
• prompt_extend 기본 활성화. 모델이 프롬프트를 자동으로 확장합니다. 엄격한 레이아웃이나 텍스트 복제가 필요할 때는 false로 설정합니다.

선화에서 3D 장난감으로의 변환은 한 번의 편집 요청이며 원본 이미지의 형태, 비율, 자세가 유지됩니다:

참조 이미지의 선화 작은 로봇을 정교한 3D 카툰 장난감 렌더링으로 변환: 무광 화이트 외壳에 코럴 오렌지 관절, 귀, 안테나를 조합하고 가슴의 하트가 부드러운 핑크빛을 발하며 눈은 밝은 파란색입니다. 기존 형태, 비율, 자세를 유지하고 부드러운 스튜디오 조명, 깨끗한 연한 회백색 배경, 로봇 본체만 유지합니다.

이 프롬프트로 생성하기 → 링크는 프롬프트만 미리 채우며, 열고 나서 선화를 업로드하고 화면 비율을 1:1로 선택하세요.

온라인 체험: 5단계로 첫 이미지 생성

1. Qwen Image 2.1 Pro 모델 페이지를 엽니다. 200 크레딧이면 Pro 2장을 생성할 수 있습니다.
2. 프롬프트를 작성합니다. 편집할 때는 먼저 1–10장의 참조 이미지를 image_urls에 업로드합니다.
3. 화면 비율을 선택하거나 비워 두면 모델이 자동으로 선택합니다.
4. prompt_extend는 기본 활성화입니다. 엄격한 레이아웃의 중국어 포스터는 먼저 끄세요.
5. 제출하고 이미지가 나오면 다운로드합니다.

API 연동: 4단계로 실행

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks에 model을 qwen-image-2.1-pro로 입력합니다.
3. taskId를 받은 후 GET /v1/tasks/{taskId}를 폴링하거나 callback을 설정합니다.
4. status가 success가 되면 output[0].url에서 이미지를 다운로드합니다.

실행 가능한 curl: 텍스트→이미지

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "input": {
      "prompt": "미니멀한 중국어 이벤트 포스터, 아이보리색 종이 배경, 화면 중앙에 다음 세 줄의 중국어 텍스트만 모두 가로 중앙 정렬로 배치: 첫째 줄은 큰 검은색 세리프 글씨 「春日茶会」, 둘째 줄은 중간 크기 짙은 회색 글씨 「三月二十八日 下午两点」, 셋째 줄은 작은 회색 글씨 「城南茶室 免费入场」. 자간은 균일하고 사방 여백이 충분하며, 이 세 줄 외에 화면에 다른 텍스트, 도형, 선, 장식이 전혀 없음, 무광 인쇄 질감.",
      "aspect_ratio": "3:4",
      "prompt_extend": false,
      "seed": 42
    }
  }'

작업 ID는 data.taskId에 있습니다:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status는 queued, handling, archiving, success 또는 fail을 거칩니다. archiving은 아직 패키징 중이라는 뜻이며 실패가 아닙니다.

Python 버전: 생성, 폴링, 다운로드

import time
import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "qwen-image-2.1-pro",
    "input": {
        "prompt": "밀짚모자를 쓴 시바견이 서핑보드를 타고 있는 모습, 플랫 스티커 스타일, 코럴 오렌지와 오션 블루 배색, 단색 배경.",
        "aspect_ratio": "1:1",
        "seed": 42,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(3)

if data["status"] == "success":
    with open("qwen-image.png", "wb") as f:
        f.write(requests.get(data["output"][0]["url"], timeout=60).content)
    print("saved qwen-image.png")
else:
    print(data.get("error"))

텍스트→이미지와 편집의 차이: image_urls

image_urls를 전달하지 않으면 완전히 새로운 이미지가 나옵니다. 1장이면 단일 이미지 편집, 2–10장이면 다중 이미지 참조입니다. 참조 이미지는 JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF를 지원하고 장당 ≤10MB, 너비/높이 1–8000px, 장단변 비율 ≤10:1입니다.

여러 장일 때 image_urls 배열 순서가 곧 프롬프트의 「图1」「图2」입니다. 이 의자를 거실에 넣을 때 두 장의 참조 이미지와 하나의 프롬프트를 사용합니다:

图1의 오크 원목 팔걸이 의자를 图2의 거실에 넣고, 의자는 통창 앞 바닥 빛무늬 위에 배치하며 방향은 图1과 일치하게 유지하고, 의자에 장면에 맞는 바닥 그림자와 접촉 그림자를 보완합니다. 图2 방의 벽면, 나무 바닥, 걸레받이, 창틀과 창밖 풍경은 완전히 그대로 유지하고, 전체를 오후의 따뜻한 흰색 자연 측광으로 통일합니다.

이 프롬프트로 생성하기 → 열고 나서 图1 의자, 图2 거실 순서로 업로드하세요. 순서가 바뀌면 결과도 바뀝니다.

단일 이미지 편집도 image_urls를 사용합니다. 이 향수병은 재질과 장면만 변경합니다:

图1의 향수병을 기반으로 이커머스 제품 이미지 리터치: 병 유리를 무광 반투명 질감으로 변경, 병뚜껑을 은회색 금속에서 브러시드 황동으로 교체, 병 안의 향수액을 짙은 앰버색으로 변경, 병을 짙은 녹색 대리석 상판 위에 배치, 배경을 따뜻한 회색 벽면으로 교체, 왼쪽 위 측면 역광으로 병身 윤곽을 강조하고, 图1의 병身 형태, 비율, 병뚜껑 높이와 라벨 영역 형태는 그대로 유지합니다.

이 프롬프트로 생성하기 → 열고 나서 향수 원본 이미지를 업로드하고 1:1을 선택하세요.

prompt_extend와 투명 배경

prompt_extend는 기본이 true이며 모델이 짧은 설명을 완전한 화면 지시로 확장합니다. 고정 레이아웃을 복제하거나 글자 단위 포스터를 만들거나 프롬프트가 이미 매우 상세할 때는 false로 설정하면 모델이 원문 그대로 실행합니다.

투명 배경은 프롬프트로 생성합니다. 「완전 투명 배경, 본체만 유지, 배경 색상 블록 없음」이라고 작성하면 출력 PNG에 투명 채널이 포함될 수 있습니다. 결과는 작성 방식에 민감하며 완전 투명을 보장하지 않습니다. 전달 전에 Image.open(path).getchannel("A").getextrema()로 alpha를 확인하고, 안정적인 투명 배경이 필요하면 추가로 배경 제거를 보완하세요.

출시 전 주의할 3가지

1. 콜백에 폴링 폴백 추가. 요청 본문 최상위에 "callback": {"url": "https://yourapp.com/hook", "when": "final"}를 추가하면 최종 상태를 통지합니다. 콜백은 중복될 수 있으므로 taskId로 중복 제거하고 정기 조회를 유지하세요.
2. 타임아웃 시 다시 POST하지 마세요. 제출할 때마다 새 이미지, 새 과금입니다. taskId를 저장하고 네트워크 흔들림이 있을 때 같은 ID를 조회하세요.
3. aspect_ratio를 명시하세요. 작성하지 않으면 모델이 선택합니다. 비율을 고정하려면 다섯 가지 중 하나를 작성하세요. resolution 필드는 없으며 전달하면 오류가 발생합니다. 결과物 URL에는 expireAt이 있으므로 받자마자 다른 곳에 저장하세요.

자주 묻는 질문

참조 이미지는 최대 몇 장까지 전달할 수 있나요? 1–10장이며 장당 10MB를 초과할 수 없습니다. 여러 장일 때는 「图1」「图2」로 지칭합니다.

4K를 선택할 수 있나요? 없습니다. 다섯 가지 화면 비율은 고정된 2K급 크기이며 1:1 최대 2048×2048입니다.

투명 배경을 보장하나요? 보장하지 않습니다. 투명 배경은 프롬프트로 생성되며, 이미지 생성 후 alpha 채널을 확인하고 필요하면 배경 제거를 보완하세요.

지금 바로 첫 이미지 생성하기

선화 로봇 프롬프트를 복사하고 Qwen Image 2.1 Pro 모델 페이지를 열어 선화를 업로드하고 1:1을 선택하면 $0.05로 2048×2048 한 장을 생성합니다. 다중 이미지 합성을 하려면 의자와 거실을 순서대로 image_urls에 전달하고 다시 실행하세요. 전체 파라미터는 연동 문서에서 확인하세요.

관련 읽기: Qwen Image 2.1 가격 · Qwen Image 2.1 vs GPT Image 2.5 · Qwen Image 2.1 프롬프트 모음