Qwen Image 2.1 Turbo API 사용 방법: curl, Python 및 실제 요청 1회 테스트

Qwen Image 2.1 Turbo(qwen-image-2.1-turbo)는 hiapi에서 제공하는 알리바바 2.1 이미지 시리즈 중 속도가 빠르고 가격이 낮은 등급입니다. 텍스트 프롬프트를 받고 선택적으로 0–10장의 참조 이미지를 받아 2048×2048 PNG 한 장을 반환합니다. 이 가이드는 바로 실행 가능한 요청, API가 실제로 강제하는 입력 스키마, 편집 호출 1회, 그리고 '투명 PNG'라는 주장을 테스트할 때 확인한 결과를 제시합니다.

hiapi API 키는 콘솔에서 발급받으세요. 호출은 통합 비동기 작업 API를 통해 이루어지므로 동기 이미지 응답은 없습니다.

최소 요청: 텍스트 → 이미지

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "스티커 스타일 일러스트: 밀짚모자를 쓴 시바견이 서핑보드에 앉아 있는 모습, 플랫 컬러, 굵은 외곽선, 산호색과 바다색",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

그런 다음 GET /v1/tasks/<taskId>를 data.status가 success가 될 때까지 폴링하고 data.output[0].url을 읽으세요.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # 주의: 필드는 taskId이며 id가 아님

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # 일시적 네트워크 오류: 같은 id로 계속 폴링
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

파일은 즉시 다운로드하세요. 출력 URL은 temp.hiapi.ai에 있으며 expireAt 타임스탬프가 붙습니다(저희 실행에서는 생성 후 약 7일). 더 오래 보관하려면 파일 바이트를 직접 저장하세요.

입력 스키마(API가 실제로 강제하는 규칙)

다음 내용은 의도적으로 잘못된 요청을 보냈을 때 반환된 검증 오류에서 가져온 것이므로, 문서의 재서술이 아니라 라이브 엔드포인트의 실제 동작을 반영합니다:

필드	규칙
prompt	필수 문자열(모델 페이지의 폼에서는 상한을 4500자로 설정)
aspect_ratio	값은 1:1, 16:9, 9:16, 4:3, 3:4 중 하나
image_urls	참조 이미지 URL 배열, 0–10개. 문자열을 직접 전달하면 거부되며 image_urls must be an array가 반환됨
prompt_extend	불리언, 프롬프트 최적화 스위치
seed	정수, 0부터 2147483647까지

같은 시리즈의 다른 Qwen 모델과 다른 점이 두 가지 있습니다. 여기에는 resolution 필드가 없습니다. 이 필드를 보내면 additional properties 'resolution' not allowed가 반환됩니다. 1:1의 경우 출력은 고정된 2048×2048 캔버스이며, 이는 실측으로 확인했습니다. 또한 알 수 없는 필드는 보통 무시되지 않고 거부됩니다. 잘못된 aspect_ratio는 error_code: INVALID_REQUEST와 함께 HTTP 400을 반환하며 message에 허용 값을 나열합니다.

참조 이미지로 편집하기

편집과 스타일 재그리기는 같은 모델 id를 사용합니다. 원본 이미지를 image_urls에 넣고 프롬프트에 수정 내용을 설명하세요:

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "밀짚모자를 짙은 보라색으로 다시 채색하고 나머지 부분은 그대로 유지",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

실제 실행에서 관찰한 결과

2026-10-24에 텍스트 → 이미지 호출 1회와 편집 호출 1회를 실행했으며, 둘 다 seed: 42, aspect_ratio: "1:1"을 사용했습니다.

• 지연: 텍스트 → 이미지는 생성 후 약 29초에 success에 도달했습니다(작업 created에서 completed 타임스탬프까지). 편집은 약 22초 걸렸습니다. 상태는 success에 들어가기 전에 여러 번의 폴링 동안 archiving을 거치므로 비종료 상태를 오류로 보지 마세요. 이는 표본 두 개일 뿐 벤치마크가 아닙니다.
• 출력: 둘 다 2048×2048 PNG를 반환했으며, 텍스트 → 이미지 결과는 약 3.9 MB였습니다.
• 편집 동작: 첫 출력을 다시 입력하고 모자를 보라색으로 바꾸도록 요청했습니다. 결과는 개, 자세, 파도, 레이아웃을 유지했고 모자 끈과 리본을 보라색 쪽으로 치우치게 했습니다. 모자의 밀짚 몸체는 대체로 밀짚색으로 남았습니다. 질감이 있는 물체의 색상 수정에서 편집의 지시 따르기는 부분적으로만 적용될 수 있으므로, 프롬프트는 막연히 묘사하기보다 구체적으로(예: "모자 끈을 다시 채색") 작성해야 합니다.
• 투명 배경: 알파 채널이 완전히 불투명합니다. 모델 페이지는 투명 배경 PNG 출력을 홍보하며, 저희는 프롬프트에 "완전히 투명한 배경, 피사체와 스플래시 효과만 유지"라고 적었습니다. 반환된 파일은 RGBA였지만 모든 픽셀의 알파가 255(투명 픽셀 0개)였고 모서리는 연한 회백색(예: (241, 243, 248, 255))이었습니다. 이미지를 열어 보니 모델은 픽셀을 투명하게 두는 대신 희미한 체커보드 스타일 배경을 픽셀에 그려 넣었습니다. 편집 출력도 동일했습니다(최소 알파 241). 따라서 저희 실행에서는 프롬프트만으로는 색상 페이지에 바로 올릴 수 있는 누끼를 얻지 못했습니다. 이 결과는 한 가지 프롬프트 작성 방식에만 해당하며, 투명도를 전환하는 요청 필드는 찾지 못했습니다(transparent는 알 수 없는 속성으로 거부됨). 진짜 알파 채널이 필요하다면 851-labs 배경 제거 가이드를 참고하는 등 배경 제거 단계를 계획하고, 출시 전에 Image.open(f).getchannel("A").getextrema() 같은 픽셀 검사로 검증하세요.

프로덕션 환경 주의사항

• 높은 동시성에서는 폴링 대신 콜백 사용: 작업 요청 본문에 "callback": {"url": "https://your.app/hook", "when": "final"}을 추가하고, 콜백은 힌트로 취급한 뒤 GET /v1/tasks/<taskId>로 결과를 확인하세요.
• taskId 보존: 폴링이 네트워크 오류로 실패하면 다시 제출하지 말고 같은 id로 폴링하세요. 다시 제출하면 두 번째 작업이 생성되어 과금됩니다.
• seed 고정으로 프롬프트를 조정할 때 비교 가능한 출력을 얻으세요. 다만 이는 최선 노력이며 확실한 보장은 아닙니다.
• 과금 전 검증: 스키마 오류(HTTP 400, INVALID_REQUEST)는 생성 시점에 반환되며, 이때 아직 이미지는 생성되지 않았습니다.

어떤 등급을 선택할까

같은 시리즈에는 Qwen Image 2.1 Pro도 있으며, 가격 페이지에 표시된 이미지당 가격이 Turbo보다 높습니다. 둘 다 텍스트 → 이미지, 편집, 0–10장 참조 이미지를 지원한다고 설명되어 있지만, 저희는 Turbo만 실행했으므로 상대적 이미지 품질에 대해서는 어떤 단정도 하지 않습니다. Turbo의 장점은 더 낮은 가격과 8스텝 속도이므로, 소재에서 출력 품질이 더 중요하다면 같은 프롬프트와 seed로 두 모델을 각각 실행해 비교하세요. 더 새로운 Qwen 3.0 세대는 Qwen Image 3.0 API 가이드와 Qwen Image 3.0 Pro 가이드를 참고하세요.

관련 자료

• Qwen Image 2.1 Turbo 모델 페이지
• 가격
• Qwen Image 3.0 API 가이드
• 문서

자주 묻는 질문

모델 id는 무엇인가요? qwen-image-2.1-turbo이며 POST /v1/tasks로 보냅니다.

출력 해상도를 선택할 수 있나요? 이 스키마에서는 불가능합니다. resolution 필드가 없습니다. 허용된 다섯 값 중 하나를 aspect_ratio로 선택하세요.

편집을 지원하나요? 지원합니다. image_urls에 1–10장의 원본 이미지를 넣고 지시 프롬프트를 함께 보내세요. 저희 테스트에서는 질감이 있는 영역의 색상 편집이 부분적으로만 적용되었습니다.

투명 PNG를 반환하나요? 저희 테스트에서는 아니었습니다. 파일은 RGBA 모드였지만 알파 채널이 완전히 불투명했고 그려진 배경이 포함되어 있었습니다. 알파를 직접 검증하고, 진짜 투명도가 필요하면 배경 제거 단계를 추가하세요.

가격은 얼마인가요? 가격 페이지를 참고하세요. 작성 시점 기준으로 두 2.1 등급 중 더 낮은 가격입니다.