WaveSpeedAI

Qwen Image 2512 API 빠른 시작: 몇 분 안에 이미지 생성 (2026)

Qwen Image 2512 API 빠른 시작: 몇 분 안에 이미지 생성 (2026)

안녕하세요, 저는 도라입니다. 저는 제품용 이미지를 만드느라 많은 시간을 보냈습니다: 이미지 찾기, 크기 조정, 파일 이름 바꾸기, 폴더 정리하기… 끝없이 반복되는 모든 단계들. 어떤 것도 어렵지는 않았지만, 지루했습니다. 나중에 Qwen Image 2512 API를 시도해 봤고, 단 몇 줄의 코드로 이 모든 것을 자동화할 수 있다는 것을 발견했습니다.

이것은 광고가 아닙니다. 저는 단지 실제로 이것을 시도했을 때 무엇이 일어났는지, 무엇이 순조롭게 진행됐는지, 어디서 막혔는지, 그리고 이것을 안정적으로 유용하게 만든 방법을 공유하고 있을 뿐입니다.

WaveSpeed 바로가기 (결과만 원하시는 분들을 위해)

빠르게 이미지를 생성하고 싶지만 모든 것을 직접 연결하고 싶지 않으신 경우:

  • WaveSpeed는 이미 사용 가능한 Qwen Image 2512 REST API를 제공합니다 (콜드 스타트 없음).
  • WaveSpeed 엔드포인트 + API 키 → 끝입니다.
  • 공식 DashScope 흐름을 이해하고 싶으신 경우 (그리고 일반적인 함정들), 계속 읽으세요.

이 API는 실제로 무엇을 할 수 있나요?

간단히 말해서: 텍스트로 설명을 입력하면 이미지를 얻습니다.

예를 들어, 다음과 같이 쓰면:

“부드러운 빛 아래 노트북과 식물이 있는 깔끔한 책상”

몇 초 후, 설명과 일치하는 이미지를 받게 되며, 컴퓨터에 자동으로 저장할 수 있습니다.

이것이 좋은 점:

  • 무드보드 만들기
  • 썸네일 빠르게 생성하기
  • 문서에 플레이스홀더 이미지 추가하기
  • 제품 프로토타입 시각화 만들기

내가 발견한 것:

처음 사용했을 때, 이미지를 수동으로 찾는 것보다 훨씬 빠르지는 않은 것처럼 느껴졌습니다. 하지만 2~3번 실행한 후, 더 이상 “이 이미지의 크기는 얼마여야 할까?” 또는 “파일 이름을 어떻게 지을까?”라고 고민할 필요가 없다는 것을 깨달았습니다. 절약된 것은 시간뿐 아니라 정신적 에너지였습니다.

이미지 형식 및 저장소

  • 형식: PNG, 기본적으로 자동 생성
  • 이미지가 저장되는 위치:
    • API는 이미지에 대한 링크(URL)를 반환합니다
    • 링크는 알리바바 클라우드 서버를 가리킵니다
    • 중요: 링크는 24시간 동안만 유효하며, 그 이후로는 만료됩니다
    • 따라서 신속하게 컴퓨터에 다운로드해야 합니다

참고: API는 직접 이미지 파일을 제공하지 않습니다. 로컬에 저장하려면 코드에 다운로드 단계를 추가해야 합니다 (나중에 설명).

시작 전에: 필요한 것

단계 1: 계정 및 API 키 받기

  1. 알리바바 클라우드 계정에 가입하세요
  2. 모델 스튜디오 콘솔로 이동합니다
  3. API 키를 생성합니다 (당신이라는 것을 증명하는 키)
  4. 키를 DASHSCOPE_API_KEY라는 환경 변수로 저장합니다 환경 변수: 컴퓨터의 특별한 위치로 생각하면 됩니다. 여기서 키가 저장되어 있어서 코드가 매번 복사-붙여넣기할 필요 없이 자동으로 찾을 수 있습니다.

팁:

  • 테스트를 위해 .env 파일에 저장할 수 있습니다
  • 실제 사용을 위해서는 안전한 키 관리 도구가 더 안전합니다
  • 베이징과 싱가포르 지역의 키는 서로 다릅니다 — 섞지 마세요

단계 2: 도구 선택하기

세 가지 주요 방법이 있으며, 가장 간단한 것부터 시작합니다:

  1. cURL (가장 간단)

    • API가 작동하는지 빠르게 테스트하기에 좋습니다
    • 프로그래밍이 필요하지 않으며, 단지 명령어를 붙여넣으면 됩니다
    • 처음 시도할 때 추천합니다

  2. Python (가장 흔함)

    • 반복 사용을 위한 작은 도구를 만들기에 좋습니다
    • 저는 공식 DashScope SDK를 사용하여 많은 세부사항을 자동으로 처리합니다
    • 기본적인 Python 지식이 도움이 됩니다

  3. Node.js (프론트엔드 개발자에게 친화적)

    • 프론트엔드 개발자라면 이것도 작동합니다
    • 원칙은 같지만, 여기서는 다루지 않겠습니다

먼저 플레이그라운드를 시도해보세요: 결과를 빠르게 테스트하고 싶다면, Wavespeed 플레이그라운드를 통해 브라우저에서 이미지를 생성할 수 있습니다. 가끔 사용할 때 완벽합니다. 배치 생성이나 자동화를 위해서는 계속 읽고 API 사용 방법을 배우세요.

빠른 시작: cURL로 테스트하기

터미널(Mac) 또는 명령 프롬프트(Windows)를 열고 다음을 붙여넣으세요:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data '{
    "model": "qwen-image-max",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {"text": "부드러운 빛 아래 노트북과 식물이 있는 깔끔한 책상"}
          ]
        }
      ]
    },
    "parameters": {
      "size": "1024*1024"
    }
  }'

Enter를 누르고 몇 초 기다리면, 이미지 링크가 포함된 JSON 응답을 보게 됩니다.

마주친 함정들

  1. 모델 이름은 qwen-image-max여야 하며, qwen-image-2512나 다른 것이 아닙니다.
  2. 크기 형식은 1024x1024이 아니라 1024*1024 (별표)를 사용합니다.
  3. 싱가포르 지역의 경우, URL을 다음으로 변경하세요: https://dashscope-intl.aliyuncs.com/api/v1/...

프로덕션 같은 것을 만들고 있다면, 공식 DashScope 흐름은 완전히 작동합니다 — 하지만 운영 세부사항 (지역, URL 수명, 재시도)이 함께 옵니다. 이것이 정확히 제가 일상 업무에 WaveSpeed를 사용하는 이유입니다: 준비된 REST API 뒤에 Qwen Image 2512를 제공하므로, 배관 대신 프롬프트와 출력 관리에 집중할 수 있습니다.

매개변수 설명

필수

  1. model

    • "qwen-image-max"는 Qwen-Image-2512의 공식 이름입니다
    • 비슷하지만 더 저렴한 "qwen-image-plus"도 있습니다

  2. input.messages

    • 하나의 요소를 가진 배열입니다
    • text는 당신의 설명입니다
    • 최대 800자 (약 400 중국어 자)

선택사항 (생략 시 기본값 사용)

  1. parameters.size

    • 1664*928 (16:9 가로)
    • 1472*1104 (4:3)
    • 1328*1328 (1:1 정사각형, 기본값)
    • 1104*1472 (3:4 세로)
    • 928*1664 (9:16 세로)

  2. parameters.negative_prompt

    • 원하지 않는 것: 예: "low-res, blurry, distorted, oversaturated"
    • 최대 500자

  3. parameters.prompt_extend

    • 기본값은 true입니다
    • 자동으로 설명을 풍부하게 합니다
    • 엄격한 제어를 원하면 끄세요

  4. parameters.watermark

    • 기본값 false
    • true인 경우 “Qwen-Image” 워터마크를 추가합니다

  5. parameters.seed

    • 범위 0–2147483647
    • 동일한 seed + 동일한 설명 = 동일한 이미지
    • 테스트 및 결과 비교에 유용합니다

API 응답 예제

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "width": 1328,
    "image_count": 1,
    "height": 1328
  },
  "request_id": "xxx"
}

핵심 포인트

  • 이미지 URL: output.choices[0].message.content[0].image
  • finish_reason이 "stop"인지 확인하여 성공을 확인합니다
  • 링크는 24시간 지속됩니다 — 신속하게 다운로드하세요

Python으로 자동화하기

배치 생성이나 작은 도구를 원하는 경우:

import os
import time
import requests
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath

API_KEY = os.getenv("DASHSCOPE_API_KEY")
ENDPOINT = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"

HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

def generate_image(prompt: str, size="1328*1328"):
    payload = {
        "model": "qwen-image-max",
        "input": {
            "messages": [{"role": "user", "content": [{"text": prompt}]}]
        },
        "parameters": {"size": size, "prompt_extend": True, "watermark": False}
    }
    r = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=120)
    r.raise_for_status()
    data = r.json()
    choices = data.get("output", {}).get("choices", [])
    if not choices:
        raise ValueError(f"No image generated:\n{data}")
    content = choices[0].get("message", {}).get("content", [])
    if not content:
        raise ValueError(f"Empty content:\n{data}")
    image_url = content[0].get("image")
    if not image_url:
        raise ValueError(f"No image URL:\n{data}")

    img_response = requests.get(image_url)
    img_response.raise_for_status()

    file_name = PurePosixPath(unquote(urlparse(image_url).path)).parts[-1]
    ts = int(time.time())
    path = f"qwen_image_{ts}_{file_name}"
    with open(path, "wb") as f:
        f.write(img_response.content)
    return path

if __name__ == "__main__":
    output_path = generate_image("부드러운 빛 아래 노트북과 식물이 있는 깔끔한 책상")
    print("Image saved at:", output_path)

테스트하면서 배운 것

  • 잘못된 모델 이름은 작동하지 않습니다 (qwen-image-plus → qwen-image-max)
  • 잘못된 크기 형식 (1328x1328 대신 1328*1328)
  • 응답 구조가 문서와 약간 다릅니다; 이미지 URL을 확인하세요
  • 이미지 다운로드를 잊으면 링크는 24시간 후 만료됩니다

공식 SDK 사용하기

import os
import json
from dashscope import MultiModalConversation

api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [{"role": "user", "content": [{"text": "부드러운 빛 아래 노트북과 식물이 있는 깔끔한 책상"}]}]

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-max",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    size='1328*1328'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
    image_url = response.output.choices[0].message.content[0]['image']
    print(f"Image URL: {image_url}")
else:
    print(f"Error: {response.code} - {response.message}")

빠른 매개변수 참고

매개변수권장값참고
size1328*1328정사각형, 균형 잡힌 속도와 품질
prompt_extendTRUEAI가 설명을 풍부하게 하도록 합니다
seed고정 숫자결과 비교를 위해 사용합니다
negative_prompt필요시예: “blurry, low quality, distorted”

Seed를 변경할 시기

  • 고정 seed → 프롬프트 변형 비교
  • 다양한 seed → 여러 개의 서로 다른 이미지 생성

일반적인 오류 & 해결책

  • 401 Unauthorized → 잘못된 API 키, 잘못된 지역, 또는 누락된 이미지 권한
  • 429 Rate limit → 너무 많은 요청; 지연을 추가하거나 할당량을 업그레이드하세요
  • 시간 초과 / 네트워크 문제 → 시간 초과를 늘리고, 즉시 다운로드하세요

추가한 작은 개선사항들

  1. 고정 seed로 테스트 → 결과 비교가 더 쉬워집니다
  2. 일관된 파일 이름 지정: {keyword}-{size}-{seed}.png
  3. 구성 파일 관리: 매개변수 하드코딩을 피하기 위해 YAML 사용

이것이 작동하는 대상

플레이그라운드

  • 가끔 이미지 생성
  • 빠른 프롬프트 테스트
  • 자동화 필요 없음

API

  • 배치 생성
  • 도구 또는 제품 통합
  • 예정된 또는 시스템 기반 사용

최종 경로 (당신에게 맞는 것을 선택하세요)

경로 A — 빠르고 실용적

경로 B — 완전한 제어

  • 깊은 알리바바 클라우드 통합이 필요하면 DashScope를 직접 사용하세요

나는 조용히 백그라운드에서 작동하는 도구를 좋아합니다. 배우고 이해하기 위해서는 공식 흐름이 훌륭합니다. 일상 업무와 더 빠르게 배포하기 위해서는 WaveSpeed가 많은 마찰을 덜어줍니다.