Qwen Image 2.1 무료 API: ModelScope로 이미지 생성하기

Qwen-Image-2.1을 프로그램에서 무료로 호출하려면 ModelScope의 API-Inference를 이용하면 됩니다. 2026년 9월 23일 확인 기준, 정확한 2.1 모델 페이지에 무료 추론 API와 Qwen/Qwen-Image-2.1 호출 예제가 공개되어 있습니다. ModelScope 계정에 실명 인증을 마친 Alibaba Cloud 계정을 연결하고, Access Token과 사용 가능한 무료 연산 잔액을 준비해야 합니다.

호출 순서는 간단합니다. 이미지 생성 요청으로 task_id를 받은 뒤, 같은 작업의 상태를 조회하고, SUCCEED가 되면 output_images에 담긴 URL에서 이미지를 내려받습니다. 이 글의 코드는 공개 문서를 바탕으로 작성했으며 실제 이미지 생성 요청을 실행해 검증한 예제는 아닙니다.

무료 API를 쓰기 전에 준비할 것

먼저 ModelScope의 API-Inference 안내에 따라 계정을 준비합니다. 한국어로 안내된다고 해서 한국에서 만든 모든 계정의 이용 자격이 자동으로 보장되는 것은 아닙니다. 공식 문서에 국가별 자격표는 없으므로 실제 가입·연결·인증 절차를 완료할 수 있는지가 기준입니다.

1. ModelScope에 가입하고 로그인합니다.
2. 개인 정보를 작성하고 이메일 인증을 완료합니다. 이는 무료 연산 잔액인 魔粒를 사용하는 데 필요한 조건입니다.
3. Alibaba Cloud 계정을 연결하고 해당 클라우드 계정의 실명 인증을 완료합니다.
4. 개인 Access Token 페이지에서 토큰을 확인하거나 발급합니다. 토큰 안내 문서도 함께 참고할 수 있습니다.
5. Qwen-Image-2.1 모델 페이지의 API-Inference 영역에서 제공자가 魔搭社区인지, 현재 예상 차감량과 계정 잔액이 얼마인지 확인합니다.

여기서 필요한 값은 ModelScope 토큰입니다. Alibaba Cloud 계정을 연결했다고 해서 DashScope API 키를 대신 넣는 방식은 아닙니다. 토큰은 아래처럼 환경 변수로 전달하고, 공개 저장소나 프런트엔드 JavaScript에 넣지 마세요.

bash
python -m pip install requests Pillow
export MODELSCOPE_TOKEN='발급받은_ModelScope_토큰'

Python으로 제출부터 PNG 저장까지

ModelScope의 모델 페이지에 실린 비동기 API를 사용합니다. 모델 이름은 대소문자와 버전을 포함해 Qwen/Qwen-Image-2.1 그대로 넣습니다. 일반 안내 문서의 이전 모델 이름이나 다른 제공자의 모델 ID로 바꾸면 같은 모델을 호출한다는 보장이 없습니다.

위 필드와 경로의 근거는 ModelScope 2.1 모델 페이지의 API 예제입니다. 아래 코드는 여기에 요청별 HTTP 타임아웃, 5분의 전체 폴링 제한, 환경 변수 처리와 PNG 저장을 더한 구현 예시입니다. 이 시간 설정은 서비스가 보장하는 생성 시간이 아니라 프로그램이 기다릴 시간을 정한 것입니다.

다음 내용을 generate_qwen.py로 저장합니다.

python
import os
import time
from io import BytesIO
from pathlib import Path

import requests
from PIL import Image


BASE_URL = "https://api-inference.modelscope.cn"
TOKEN = os.environ["MODELSCOPE_TOKEN"]
API_HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}
HTTP_TIMEOUT = (10, 60)  # 연결, 응답 대기 시간(초)
POLL_LIMIT_SECONDS = 300


def main():
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            **API_HEADERS,
            "X-ModelScope-Async-Mode": "true",
        },
        json={
            "model": "Qwen/Qwen-Image-2.1",
            "prompt": "햇살이 드는 창가에 앉은 금빛 고양이, 수채화",
        },
        timeout=HTTP_TIMEOUT,
    )
    response.raise_for_status()
    task_id = response.json()["task_id"]
    print("접수된 작업:", task_id)

    deadline = time.monotonic() + POLL_LIMIT_SECONDS
    while True:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError(
                f"조회 대기 시간 초과. 재제출 전에 작업 상태를 확인하세요: {task_id}"
            )

        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={
                **API_HEADERS,
                "X-ModelScope-Task-Type": "image_generation",
            },
            timeout=(min(10, remaining), min(30, remaining)),
        )
        response.raise_for_status()
        data = response.json()
        status = data["task_status"]

        if status == "SUCCEED":
            image_urls = data.get("output_images") or []
            if not image_urls:
                raise RuntimeError(f"완료 응답에 이미지 URL이 없습니다: {task_id}")
            break
        if status == "FAILED":
            raise RuntimeError(f"이미지 생성 실패: {data}")

        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError(f"조회 대기 시간 초과: {task_id}")
        time.sleep(min(5, remaining))

    # 결과 파일 서버에는 ModelScope 토큰을 보내지 않습니다.
    download = requests.get(image_urls[0], timeout=HTTP_TIMEOUT)
    download.raise_for_status()
    output_path = Path("qwen-image-2-1.png")
    with Image.open(BytesIO(download.content)) as image:
        image.save(output_path, format="PNG")
    print("저장 완료:", output_path.resolve())


if __name__ == "__main__":
    main()

실행 명령은 다음과 같습니다.

bash
python generate_qwen.py

성공 기준은 터미널에 작업 번호가 출력되는 것만이 아닙니다. 작업 상태가 SUCCEED이고, 결과 URL을 내려받아 qwen-image-2-1.png 파일이 실제로 저장되어야 합니다. 예제는 첫 번째 결과 이미지를 저장합니다. PNG를 사용하므로 원본 결과에 투명도가 있다면 JPEG로 변환하면서 사라지는 문제를 피할 수 있습니다. 이것이 위 프롬프트에 투명 배경 생성을 요청했다는 뜻은 아닙니다.

5분 뒤 프로그램이 멈춰도 서버의 작업이 취소되었다고 볼 수는 없습니다. 출력된 task_id를 남겨 두고 같은 상태 조회 주소에서 확인하세요. 응답이 늦다는 이유만으로 생성 요청을 다시 제출하면 별도의 작업이 만들어질 수 있습니다.

무료로 몇 장까지 만들 수 있나요?

현재 규칙은 고정 이미지 장수가 아니라 계정의 魔粒 잔액을 기준으로 합니다. ModelScope의 API-Inference 제한 안내는 경량·일반·플래그십 모델을 호출당 각각 0.5·1·2 魔粒로 구분합니다. 다만 이번 확인에서는 Qwen-Image-2.1의 정확한 예상 차감량이 익명 모델 페이지에 표시되지 않았습니다. 따라서 어느 등급에 속한다고 임의로 정하거나 하루 생성 가능 장수를 계산할 수 없습니다.

무료 잔액을 얻는 기본 규칙은 魔粒 안내에 나와 있습니다.

문서상 조건을 충족하면 일일 로그인으로 200에 50을 더한 단기 잔액을 받을 수 있지만, 250 魔粒가 곧 Qwen-Image-2.1 이미지 250장은 아닙니다. 실제 지급·만료 내역, 다른 기능의 사용량, 해당 모델의 표시 차감량을 확인해야 합니다. 이 글에서는 계정에 잔액이 입금되는 과정이나 생성 후 차감 결과를 실측하지 않았습니다.

검색 결과에서 볼 수 있는 하루 2,000회 또는 모델별 500회 수치를 현행 2.1 한도로 적용하지 마세요. 현재 확인한 공식 제한 문서는 잔액제를 설명합니다. 또한 동시 처리 한도는 플랫폼 부하에 따라 조정되며, ModelScope는 이 무료 서비스를 비상업적 체험용으로 안내합니다. 잔액이 남아 있다는 이유만으로 대량 동시 생성이나 운영 서비스의 가용성이 보장되지는 않습니다. 현재 서비스 제한

요청이 막힐 때 확인하는 순서

같은 코드를 반복 실행하기 전에 실패한 단계를 구분하면 불필요한 작업 제출을 줄일 수 있습니다.

이 표는 특정 HTTP 상태 코드 하나를 단일 원인으로 단정하지 않습니다. 예를 들어 인증 관련 응답이라도 토큰 오류와 계정 자격 문제는 확인할 항목이 다릅니다. 원인을 확인하지 않은 자동 재제출은 피하고, 작업 번호와 오류 메시지를 남기는 편이 좋습니다.

계정 준비가 어렵다면 공식 Hugging Face 데모도 확인하세요

Qwen 공식 Hugging Face Space는 웹 데모와 함께 Use via API 메뉴를 제공합니다. 공개된 Gradio API 안내에는 /generate_with_enhance가 있으며, 다음은 공개 스키마를 바탕으로 한 최소 호출 예제입니다.

bash
python -m pip install gradio_client

python
from gradio_client import Client

client = Client("Qwen/Qwen-Image-2.1")
result = client.predict(
    input_images=[],
    original_prompt="햇살이 드는 창가에 앉은 금빛 고양이, 수채화",
    api_name="/generate_with_enhance",
)
print(result)

공개 스키마의 반환값은 이미지 파일 정보, 시드, 보완된 프롬프트의 세 항목입니다. 이 예제 역시 실제 생성 성공을 검증한 코드는 아닙니다. 데모의 대기열과 이용 가능 상태가 바뀔 수 있으므로 실행 전 Space의 Use via API에서 최신 인수를 확인하세요. 이 방식에 ModelScope 토큰을 넣거나 데모 서버의 내부 키를 구할 필요는 없습니다.

이 경로는 공개 데모를 클라이언트로 사용하는 방법입니다. 고정 무료 할당량이나 운영용 SLA가 있는 정식 DashScope API라고 해석하면 안 됩니다. Hugging Face 모델 카드에 Inference Provider 배포가 없다고 표시되는 것과도 모순되지 않습니다. 모델 카드의 제공자 목록과 Space의 Gradio 인터페이스는 별개입니다.

DashScope 키나 무료 가중치로 대신 접속할 수 있나요?

일반 DashScope 키에 추측한 2.1 모델 이름을 넣는 방식은 이 글의 접속 방법이 아닙니다. 2026년 9월 22일 갱신된 Alibaba Cloud의 Qwen Image API 모델 목록을 확인했을 때 2.1은 기재되어 있지 않았습니다. 확인한 목록의 범위에서 내린 판단이며, 다른 곳에도 호스팅 API가 없다는 뜻은 아닙니다. 2.0이나 3.0의 모델 ID·가격·체험 한도를 2.1에 그대로 적용하지 마세요.

모델 가중치를 내려받는 경로도 별도로 있습니다. 공식 저장소는 2026년 9월 20일 공개를 안내하지만, 가중치가 공개되었다고 외부 서버의 API 사용료나 GPU 비용까지 없어지는 것은 아닙니다. 직접 실행하려면 Qwen-Image-2.1 로컬 실행 가이드를 참고하세요.

상업적 이용도 무료 호출 가능 여부와 따로 판단해야 합니다. Qwen Research License는 모델 자료의 사용을 연구·평가 목적의 비상업적 용도로 제한하고, 상업적 사용에는 별도 허가를 요구합니다. ModelScope 무료 API 자체도 비상업적 체험 서비스입니다. 이는 모든 생성물의 권리를 한 문장으로 판정한다는 뜻이 아니라, 업무나 유료 제품에 도입할 때 모델 라이선스와 호스팅 서비스의 허용 범위를 각각 확인해야 한다는 뜻입니다.

개인적인 기능 확인이라면 ModelScope에서 정확한 모델과 잔액을 확인한 뒤 이미지 한 장을 요청하는 것으로 시작하면 됩니다. 작업 번호, 완료 상태, 저장된 PNG까지 확인한 다음 반복 호출을 붙이면 첫 연동에서 어디가 작동하고 어디가 막혔는지 분명하게 구분할 수 있습니다.