Qwen Image 3.0 API 가격 및 연동 가이드

Qwen Image 3.0은 텍스트 기반 이미지 생성과 참조 이미지 편집을 하나의 비동기 API로 제공합니다. APIMart에서는 작업을 제출하고 상태를 폴링한 뒤, 작업이 완료되면 한 장 이상의 생성 이미지를 가져옵니다.

이 가이드에서는 연동 전에 알아야 할 Standard 및 Pro의 현재 가격, 인증, 요청 파라미터, 응답 파싱, 폴링, 재시도, 결과 저장 방식을 설명합니다. 모델 기능과 벤치마크는 Qwen Image 3.0 출시 가이드에서 더 자세히 확인할 수 있습니다.

Qwen Image 3.0 가격과 접근 방법

APIMart는 두 가지 Qwen Image 3.0 모델 ID를 제공합니다.

• qwen-image-3.0: Standard
• qwen-image-3.0-pro: Pro

요금은 입력 Token이 아니라 생성된 이미지 수를 기준으로 부과됩니다. 아래 금액은 2026년 8월 27일 APIMart 가격 페이지에 표시된 값이며 추후 변경될 수 있습니다.

Standard 및 Pro 가격 비교

Standard는 현재 1K와 2K 가격이 같습니다. Pro 2K는 Pro 1K의 두 배입니다. Qwen Image 3.0 API 문서에 따르면 생성 실패 시 요금이 환불되며, 참조 이미지에는 별도의 생성 요금이 붙지 않습니다.

실제 워크로드 비용 계산

기본 계산식은 다음과 같습니다.

월간 비용 = 완료된 이미지 수 × 이미지당 가격

n은 출력 수를 제어하므로 n: 4인 요청은 이미지 네 장에 대한 요금이 발생할 수 있습니다. 프롬프트 실험, 변형, 재생성까지 예산에 포함해야 합니다.

대부분의 초안과 일반 에셋에는 Standard를 사용하세요. 텍스트 렌더링, 구도 또는 세부 묘사의 향상이 추가 비용을 정당화할 때 Pro를 평가하면 됩니다. Pro를 사용한다면 반복 작업에는 1K, 승인된 고해상도 결과에는 2K를 권장합니다.

접근 권한과 인증

APIMart 계정을 만들고 충분한 잔액을 충전한 다음 콘솔에서 API 키를 생성합니다. 키는 서버 측 Secret 저장소나 환경 변수에 보관하고, 브라우저 코드 또는 NEXT_PUBLIC_* 변수에 절대 노출하지 마세요.

Base URL과 Bearer Token

이 가이드의 Base URL은 다음과 같습니다.

https://api.apimart.ai/v1

API 키를 Bearer Token으로 전송합니다.

Authorization: Bearer <your_api_key>
Content-Type: application/json

키가 없거나 유효하지 않으면 보통 401, 잔액이 부족하면 402, 속도 제한에 걸리면 429가 반환됩니다. 서버에서 응답 본문과 요청 컨텍스트를 기록하되, 로그를 저장하기 전에 API 키를 반드시 마스킹하세요.

이미지 생성·편집과 비동기 작업 흐름

생성과 편집은 모두 POST /v1/images/generations를 사용합니다. API는 이미지가 완성될 때까지 기다리지 않고 작업 ID를 먼저 반환합니다.

핵심 요청 파라미터

사용자 지정 크기는 각 변이 5122,048픽셀이고 화면 비율은 1:88:1이어야 합니다. 참조 이미지는 JPEG, PNG, BMP, TIFF, WebP, GIF를 지원하며 문서상 장당 최대 크기는 10MB입니다. 제한은 바뀔 수 있으므로 출시 전에 생성 API 문서를 다시 확인하세요.

Qwen Image 3.0 공식 발표는 12개 언어의 네이티브 텍스트 렌더링을 설명합니다. 텍스트가 많은 이미지는 정확히 표시할 문구를 따옴표로 묶고, 목표 해상도에서 철자, 글꼴 스타일, 레이아웃을 검증하세요.

텍스트-이미지 생성 예시

{
  "model": "qwen-image-3.0",
  "prompt": "‘여름 할인’ 문구를 정확히 표시한 상품 배너, 굵은 기하학적 글꼴, 따뜻한 주황색 배경",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

참조 이미지 편집 예시

기존 이미지를 변환하거나 다시 구성하려면 image_urls를 추가합니다.

{
  "model": "qwen-image-3.0-pro",
  "prompt": "제품 모양은 그대로 유지하고 배경을 부드러운 조명의 스튜디오 장면으로 교체",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

참조 URL은 API에서 접근할 수 있어야 합니다. 비공개 파일은 제출과 처리에 충분한 유효 기간을 가진 서명 URL을 사용하거나, 적절한 경우 지원되는 Data URL을 사용하세요.

비동기 작업 흐름

전체 흐름은 세 단계입니다.

1. POST /v1/images/generations로 생성 작업을 제출합니다.
2. 응답의 data[0].task_id를 읽습니다.
3. 완료 또는 실패할 때까지 GET /v1/tasks/{task_id}를 폴링합니다.

제출 응답

성공한 제출 응답의 형태는 다음과 같습니다.

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

task_id는 최상위 객체가 아니라 data 배열의 첫 번째 항목에 있습니다.

폴링 및 완료 결과

상태 요청을 계속 보내지 말고 3~5초마다 폴링하세요. 완료된 파일은 data.result.images에 있습니다.

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example-cdn.com/generated-image.png"
          ]
        }
      ]
    }
  }
}

현재 APIMart 생성 문서는 완성된 이미지가 플랫폼 CDN에 미러링되어 장기간 제공된다고 안내합니다. 그렇더라도 보존 기간, 삭제, 접근 정책 또는 전송 성능을 직접 통제해야 한다면 승인된 에셋을 자체 저장소로 복사하세요.

연동 예제

Python 연동

다음 서버 측 예시는 작업 하나를 제출하고 3초마다 폴링하며 3분 후 대기를 중단합니다.

import os
import time
import requests

API_KEY = os.environ["QWEN_API_KEY"]
BASE_URL = "https://api.apimart.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=HEADERS,
        json={"model": "qwen-image-3.0", "prompt": prompt, "resolution": "1K", "n": 1, "prompt_extend": True},
        timeout=30,
    )
    response.raise_for_status()
    task_id = response.json()["data"][0]["task_id"]
    deadline = time.monotonic() + 180

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        task = poll.json()["data"]
        if task["status"] == "completed":
            return task["result"]["images"][0]["url"][0]
        if task["status"] == "failed":
            raise RuntimeError(task.get("fail_reason", "Generation failed"))
        time.sleep(3)

    raise TimeoutError(f"Task {task_id} did not finish within 180 seconds")

실제 애플리케이션에서는 폴링 전에 작업 ID를 영구 저장하세요. Worker가 재시작되어도 다른 Worker가 저장된 작업을 이어서 처리할 수 있어 중복 생성 비용을 막을 수 있습니다.

JavaScript 연동

다음 코드는 신뢰할 수 있는 서버 환경에서만 실행하세요.

const apiKey = process.env.QWEN_API_KEY;
const baseUrl = "https://api.apimart.ai/v1";
const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, headers });
  const payload = await response.json();
  if (!response.ok) throw new Error(`APIMart ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

async function generateImage(prompt) {
  const submission = await requestJson(`${baseUrl}/images/generations`, {
    method: "POST",
    body: JSON.stringify({
      model: "qwen-image-3.0", prompt, resolution: "1K", n: 1, prompt_extend: true,
    }),
  });
  const taskId = submission.data[0].task_id;
  const deadline = Date.now() + 180_000;

  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const { data: task } = await requestJson(`${baseUrl}/tasks/${taskId}`);
    if (task.status === "completed") return task.result.images[0].url[0];
    if (task.status === "failed") throw new Error(task.fail_reason ?? "Generation failed");
  }
  throw new Error(`Task ${taskId} did not finish within 180 seconds`);
}

cURL에서도 같은 제출 및 폴링 흐름을 테스트할 수 있습니다.

curl -X POST https://api.apimart.ai/v1/images/generations \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0","prompt":"미니멀한 제품 사진","resolution":"1K","n":1}'

curl https://api.apimart.ai/v1/tasks/<task_id> \
  -H "Authorization: Bearer <your_api_key>"

프로덕션 연동 체크리스트

API 호출이 한 번 성공한 것은 시작일 뿐입니다. 안정적인 이미지 파이프라인에는 제한된 재시도, 영구적인 작업 상태, 관측 가능성, 통제 가능한 저장소가 필요합니다.

오류 및 재시도 정책

결과를 알 수 없는 네트워크 타임아웃 직후 생성 요청을 무조건 다시 제출하지 마세요. 서버가 첫 요청을 이미 수락했다면 두 번째 제출은 중복 작업과 추가 요금을 만듭니다. 반환된 작업 ID를 모두 저장하고 제출 재시도와 폴링 재시도를 구분해야 합니다.

출시 전 확인 사항

• API 키를 서버 전용 Secret에만 보관합니다.
• 제출 전에 prompt, resolution, size, n, 참조 이미지를 검증합니다.
• 작업 ID와 현재 상태를 영구 저장합니다.
• 3~5초마다 폴링하고 애플리케이션 타임아웃을 설정합니다.
• 429와 재시도 가능한 5xx에 지터가 포함된 지수 백오프를 적용합니다.
• 실제 속도 제한과 지연 시간에 맞게 동시 실행 수를 제한합니다.
• 완료, 실패, 타임아웃, 중복 작업을 별도로 추적합니다.
• 보존 정책을 직접 통제해야 한다면 승인된 결과를 자체 저장소로 복사합니다.
• 프로덕션 출시 전에 Qwen Image 3.0 모델 페이지, 가격 페이지, API 문서를 다시 확인합니다.

Qwen Image 3.0으로 이미지 생성

APIMart 통합 API로 Standard와 Pro를 테스트하고 1K와 2K 결과를 비교해 이미지 워크플로를 프로토타입에서 프로덕션으로 확장하세요.

Qwen Image 3.0 살펴보기

자주 묻는 질문

폴링은 언제 타임아웃해야 하나요?

APIMart는 3~5초마다 폴링하고 클라이언트 타임아웃을 약 3분으로 설정할 것을 권장합니다. 이를 시작점으로 사용해 실제 지연 시간에 맞게 조정하세요. 작업 ID를 보관하면 타임아웃된 작업을 나중에 확인할 수 있습니다.

결과 URL이 24시간 후 만료되나요?

현재 APIMart 생성 문서는 결과가 플랫폼 CDN에 미러링되어 장기간 제공된다고 설명합니다. 따라서 이전의 24시간 만료 설명은 이 연동에 적용되지 않습니다. 중요한 에셋은 명시적인 보존 약속이 없는 외부 저장소에만 의존하지 말고 직접 관리하는 저장소에 보관하세요.

Base64 참조 이미지를 보낼 수 있나요?

예. 현재 API 문서는 image_urls에 1~3개의 공개 HTTP/HTTPS URL 또는 지원되는 Base64 Data URL을 허용합니다. 각 이미지는 지원 형식과 10MB 제한을 충족해야 합니다.

1K와 2K 중 무엇을 선택해야 하나요?

빠른 반복 작업과 극도의 디테일이 필요 없는 에셋에는 1K를 사용하세요. 텍스트가 많거나 세밀한 가장자리, 큰 화면 표시가 필요한 최종 이미지에는 2K가 적합합니다. Standard는 현재 두 해상도의 가격이 같지만 Pro 2K는 Pro 1K보다 비싸므로 지연 시간, 품질, 비용을 함께 평가해야 합니다.