API Qwen Image 3.0: Harga dan Panduan Integrasi

Qwen Image 3.0 menggabungkan pembuatan gambar dari teks dan pengeditan gambar referensi dalam satu API asinkron. Melalui APIMart, Anda mengirim tugas, melakukan polling status, lalu mengambil satu atau beberapa gambar setelah proses selesai.

Panduan ini membahas hal penting sebelum integrasi: harga Standard dan Pro terbaru, autentikasi, parameter request, pembacaan response, polling, retry, dan penyimpanan hasil. Untuk kemampuan model dan benchmark, baca panduan rilis Qwen Image 3.0.

Harga dan Akses Qwen Image 3.0

APIMart menyediakan dua ID model:

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

Biaya dihitung per gambar yang dihasilkan, bukan per Token input. Tabel berikut mengikuti halaman harga APIMart pada 27 Agustus 2026; harga dapat berubah.

Perbandingan Harga Standard dan Pro

Standard saat ini memiliki harga yang sama untuk 1K dan 2K. Pro 2K berharga dua kali Pro 1K. Menurut dokumentasi Qwen Image 3.0, biaya pembuatan yang gagal dikembalikan dan gambar referensi tidak menambah biaya pembuatan terpisah.

Memperkirakan Beban Kerja Nyata

Rumus dasarnya adalah:

biaya bulanan = jumlah gambar selesai × harga per gambar

n menentukan jumlah output, sehingga request dengan n: 4 dapat dikenai biaya empat gambar. Masukkan eksperimen prompt, variasi, dan pembuatan ulang ke dalam anggaran.

Standard cocok untuk sebagian besar draf dan aset rutin. Pertimbangkan Pro jika peningkatan teks, komposisi, atau detail sepadan dengan biaya tambahan. Saat memakai Pro, gunakan 1K untuk iterasi dan simpan 2K untuk hasil akhir beresolusi tinggi yang sudah disetujui.

Akses dan Autentikasi

Buat akun APIMart, tambahkan saldo yang cukup, lalu buat API key di konsol. Simpan key dalam Secret atau environment variable di server; jangan pernah mengeksposnya di kode browser atau variable NEXT_PUBLIC_*.

Base URL dan Bearer Token

Contoh dalam panduan ini memakai Base URL berikut:

https://api.apimart.ai/v1

Kirim API key sebagai Bearer Token:

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

Key yang hilang atau tidak valid biasanya menghasilkan 401, saldo tidak cukup dapat menghasilkan 402, dan rate limit menghasilkan 429. Catat response dan konteks request di server, tetapi samarkan API key sebelum menyimpan log.

Pembuatan, Pengeditan, dan Alur Asinkron

Pembuatan dan pengeditan sama-sama memakai POST /v1/images/generations. API mengembalikan ID tugas terlebih dahulu tanpa menunggu gambar selesai.

Parameter Utama

Untuk dimensi khusus, setiap sisi harus 512–2.048 piksel dan rasio aspek 1:8–8:1. Referensi mendukung JPEG, PNG, BMP, TIFF, WebP, dan GIF, dengan batas terdokumentasi 10 MB per gambar. Periksa referensi pembuatan sebelum rilis karena batas dapat berubah.

Pengumuman resmi Qwen Image 3.0 menjelaskan rendering teks native dalam 12 bahasa. Apit teks yang harus muncul persis dengan tanda kutip, lalu validasi ejaan, gaya font, dan tata letak pada resolusi target.

Contoh Teks ke Gambar

{
  "model": "qwen-image-3.0",
  "prompt": "Banner produk bersih dengan teks persis \"Promo Musim Panas\", tipografi geometris tebal, latar oranye hangat",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

Contoh Edit dengan Referensi

Tambahkan image_urls untuk mengubah gambar yang sudah ada:

{
  "model": "qwen-image-3.0-pro",
  "prompt": "Pertahankan bentuk produk tanpa perubahan dan ganti latar dengan studio bercahaya lembut",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

URL referensi harus dapat diakses oleh API. Untuk file privat, gunakan signed URL yang cukup lama untuk pengiriman dan pemrosesan atau Data URL yang didukung jika sesuai.

Alur Tugas Asinkron

Alurnya terdiri dari tiga langkah:

1. Kirim tugas melalui POST /v1/images/generations.
2. Baca data[0].task_id dari response.
3. Poll GET /v1/tasks/{task_id} sampai selesai atau gagal.

Response Pengiriman

Response yang berhasil memiliki bentuk berikut:

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

Jangan membaca task_id dari objek paling atas. Nilainya berada pada item pertama di data.

Polling dan Hasil Selesai

Lakukan polling setiap tiga hingga lima detik, bukan mengirim request status tanpa henti. File yang selesai berada di data.result.images:

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

Dokumentasi APIMart saat ini menyatakan bahwa gambar selesai dicerminkan ke CDN platform dan tersedia dalam jangka panjang. Meski demikian, salin aset yang disetujui ke penyimpanan sendiri jika Anda perlu mengendalikan retensi, penghapusan, kebijakan akses, atau performa pengiriman.

Contoh Integrasi

Integrasi Python

Contoh server berikut mengirim satu tugas, melakukan polling setiap tiga detik, dan berhenti menunggu setelah tiga menit:

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")

Dalam aplikasi nyata, simpan ID tugas sebelum polling. Jika Worker dimulai ulang, Worker lain dapat melanjutkan tugas yang tersimpan tanpa mengirim dan membayar pembuatan duplikat.

Integrasi JavaScript

Jalankan kode ini hanya di lingkungan server tepercaya:

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`);
}

Alur yang sama dapat diuji dengan 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":"Foto produk minimalis","resolution":"1K","n":1}'

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

Checklist Integrasi Production

Satu panggilan API yang berhasil hanyalah awal. Pipeline yang andal juga memerlukan retry terbatas, status tugas persisten, observabilitas, dan penyimpanan yang terkontrol.

Error dan Kebijakan Retry

Jangan langsung mengirim ulang pembuatan setelah network timeout yang ambigu. Jika server menerima request pertama, pengiriman kedua dapat membuat tugas dan biaya duplikat. Simpan setiap ID yang dikembalikan dan pisahkan retry pengiriman dari retry polling.

Sebelum Peluncuran

• Simpan API key hanya dalam Secret server.
• Validasi prompt, resolution, size, n, dan referensi sebelum mengirim.
• Simpan ID dan status tugas secara persisten.
• Poll setiap tiga hingga lima detik dengan timeout aplikasi.
• Terapkan exponential backoff dan jitter untuk 429 serta 5xx yang dapat dicoba ulang.
• Batasi konkurensi berdasarkan rate limit dan latensi aktual.
• Pantau tugas selesai, gagal, timeout, dan duplikat secara terpisah.
• Salin hasil yang disetujui ke penyimpanan Anda jika retensi harus dikendalikan.
• Sebelum production, periksa kembali halaman model Qwen Image 3.0, harga, dan dokumentasi API.

Buat Gambar dengan Qwen Image 3.0

Uji Standard dan Pro melalui API terpadu APIMart, bandingkan output 1K dan 2K, lalu bawa workflow gambar Anda dari prototipe ke production.

Jelajahi Qwen Image 3.0

Pertanyaan Umum

Berapa lama polling sebelum timeout?

APIMart menyarankan polling setiap tiga hingga lima detik dan timeout client sekitar tiga menit. Gunakan sebagai titik awal, ukur latensi nyata, dan simpan ID tugas agar tugas yang timeout dapat direkonsiliasi kemudian.

Apakah URL hasil kedaluwarsa setelah 24 jam?

Dokumentasi saat ini menyatakan output dicerminkan ke CDN platform dan tersedia dalam jangka panjang. Jadi, klaim lama tentang 24 jam tidak berlaku untuk integrasi ini. Simpan aset penting dalam infrastruktur Anda, jangan hanya bergantung pada retensi eksternal tanpa jangka waktu yang dijamin.

Bisakah saya mengirim referensi Base64?

Bisa. Dokumentasi saat ini menerima satu hingga tiga URL publik HTTP/HTTPS atau Data URL Base64 yang didukung dalam image_urls. Setiap gambar harus memenuhi format yang didukung dan batas 10 MB.

Kapan memilih 1K atau 2K?

Gunakan 1K untuk iterasi cepat dan aset yang tidak memerlukan detail maksimum. Pilih 2K untuk gambar akhir dengan banyak teks, tepian halus, atau tampilan berukuran besar. Standard saat ini memiliki harga sama pada kedua resolusi, sedangkan Pro 2K lebih mahal daripada Pro 1K; nilai latensi, kualitas, dan biaya secara bersamaan.