All Products
Search
Document Center

Alibaba Cloud Model Studio:Referensi API Qwen Image Generation and Editing 3.0

Last Updated:Sep 02, 2026

Model Qwen Image Generation and Editing 3.0 mendukung baik teks-ke-gambar (T2I) maupun gambar-ke-gambar/pengeditan gambar (I2I). Model ini dapat menghasilkan gambar langsung dari prompt teks atau mengedit gambar berdasarkan 1–3 gambar referensi yang dikombinasikan dengan instruksi pengeditan.

Ikhtisar model

Model

Deskripsi

Spesifikasi gambar output

qwen-image-3.0-pro

Model Qwen Image Generation and Editing 3.0 yang mendukung teks-ke-gambar (T2I) dan gambar-ke-gambar/pengeditan gambar (I2I).

Resolusi gambar:

  • Teks-ke-gambar (T2I): Total piksel harus berada di antara 512*512 dan 2048*2048.

  • Gambar-ke-gambar (I2I): Total piksel harus berada di antara 512*512 dan 2048*2048.

  • Bawaan: Jika size tidak ditentukan, model secara otomatis merekomendasikan resolusi berdasarkan prompt.

Format gambar: PNG

qwen-image-3.0

Model standar Qwen Image Generation and Editing 3.0 yang mendukung teks-ke-gambar (T2I) dan gambar-ke-gambar/pengeditan gambar (I2I). Menyeimbangkan kualitas dan kecepatan.

Ketersediaan

Model, URL titik akhir, dan Kunci API harus berada dalam wilayah yang sama. Panggilan lintas-wilayah akan gagal.

  • Pilih model: Pastikan model tersedia di wilayah target Anda.
  • Pilih URL: Pilih URL titik akhir yang sesuai dengan wilayah model Anda. Baik URL HTTP maupun SDK DashScope didukung.
  • Konfigurasikan Kunci API: Dapatkan Kunci API untuk wilayah tersebut, lalu konfigurasikan Kunci API sebagai Variabel lingkungan.
  • Instal SDK: Untuk melakukan panggilan API menggunakan SDK, instal SDK DashScope.

CatatanKode contoh dalam topik ini berlaku untuk wilayah Singapura.

PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan migrasi ke domain baru:

  • China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan pada halaman Detail Ruang Kerja di Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi penuh.

API Sinkron (direkomendasikan)

HTTP

Singapura

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

China (Hong Kong)

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Jerman (Frankfurt)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Jepang (Tokyo)

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Parameter permintaan

Header

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Body permintaan

model string (Wajib)

Nama model. Nilai yang tersedia: qwen-image-3.0-pro dan qwen-image-3.0.

input object (Wajib)

Objek parameter input, yang berisi bidang-bidang berikut:

Properti

messages array (Wajib)

Array konten permintaan. Hanya percakapan satu putaran yang didukung, sehingga array harus berisi tepat satu objek dengan properti role dan content.

Properti

rolestring (Wajib)

Peran pengirim pesan. Harus diatur ke user.

contentarray (Wajib)

Array konten pesan, dengan kombinasi berbeda tergantung kasus penggunaan:

  • Teks-ke-gambar (T2I): Hanya berisi satu objek {"text": "..."}.
  • Gambar-ke-gambar (I2I): Berisi 1–3 objek {"image": "..."} dan 1 objek {"text": "..."}.

Properties

image string (Wajib untuk I2I)

URL atau data terenkripsi Base64 dari gambar input. Dalam skenario I2I, 1–3 gambar didukung. Saat beberapa gambar disediakan, urutannya ditentukan oleh urutan array.

Persyaratan gambar:
  • Format gambar: JPG, JPEG, PNG, BMP, TIFF, WEBP, dan GIF.
  • Resolusi gambar: Lebar dan tinggi sebaiknya antara 384 hingga 2048 piksel untuk hasil terbaik.
  • Ukuran gambar: Maksimal 10 MB.
Format input yang didukung
  1. URL publik: Protokol HTTP dan HTTPS didukung.
  2. Pengkodean Base64: Formatnya adalah data:{MIME_type};base64,{base64_data}.

textstring(Wajib)

Petunjuk positif yang menjelaskan konten, gaya, dan komposisi gambar yang ingin Anda hasilkan atau edit. Mendukung Bahasa Mandarin dan Bahasa Inggris. Jumlah maksimum yang direkomendasikan: 4.500 token.

Catatan: Hanya satu objek teks yang diizinkan. Menghilangkannya atau menyediakan beberapa objek teks akan menghasilkan error.

parameters object (Opsional)

Parameter tambahan untuk mengontrol pembuatan gambar.

Properti

prompt_extend boolean (Opsional)

Apakah akan mengaktifkan penulisan ulang prompt cerdas. Bawaan: true (direkomendasikan). Saat diaktifkan, model mengoptimalkan prompt positif menggunakan metode yang ditentukan oleh prompt_extend_mode, yang secara signifikan meningkatkan hasil untuk deskripsi sederhana.

prompt_extend_mode string (Opsional)

Metode penulisan ulang prompt. Bawaan: direct. Opsi:

  • direct: Direct Prompt Enhancement (DPE), cocok untuk sebagian besar skenario. Didukung untuk T2I dan I2I.
  • agent: Agent Prompt Enhancement (APE), memberikan penulisan ulang yang lebih rinci. Hanya mendukung teks-ke-gambar (T2I). Memberikan agent untuk gambar-ke-gambar (I2I) akan mengembalikan error 400.

enable_thinking boolean (Opsional)

Mengaktifkan mode berpikir. Bawaannya adalah true. Ini meningkatkan penalaran model untuk memperbaiki kualitas gambar, tetapi memperpanjang waktu pembuatan. Memerlukan prompt_extend=true. Didukung untuk Direct T2I, Direct I2I, dan Agent T2I. Tidak didukung untuk I2I Agent.

n integer (Opsional)

Jumlah gambar output. Rentang nilai: 1 hingga 6. Bawaan: 1.

size string (Opsional)

Resolusi gambar output dalam format width*height, misalnya "1024*1024". Jika tidak ditentukan, model secara otomatis merekomendasikan resolusi berdasarkan prompt.

  • Teks-ke-gambar (T2I): Area piksel dari 512512 hingga 20482048. Rasio aspek: 1:8 hingga 8:1.
  • Gambar-ke-gambar (I2I): Area piksel dari 512512 hingga 20482048. Rasio aspek: 1:8 hingga 8:1.

negative_prompt string (Opsional)

Prompt negatif yang menjelaskan konten yang tidak ingin muncul dalam gambar.

seed integer (Opsional)

Seed acak. Rentang nilai: [0, 2147483647]. Jika dihilangkan, layanan menghasilkan seed acak. Gunakan seed tetap untuk hasil yang dapat direproduksi.

watermark boolean (Opsional)

Apakah akan menambahkan Watermark. Bawaan: false.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads '\''Il Messaggero'\'' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street'\''s end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'

Parameter respons

output object

Berisi hasil generasi model.

Properti

rewrite_status string

Status penulisan ulang prompt. Nilainya bergantung pada apakah penulisan ulang diaktifkan dalam permintaan dan hasil penulisannya.

choices array

Daftar opsi hasil.

Properti

finish_reason string

Alasan tugas dihentikan. Nilainya adalah stop saat tugas selesai secara normal.

message object

Pesan yang dikembalikan oleh model.

Properti

rolestring

Peran pesan. Tetap sebagai assistant.

contentarray

Konten pesan yang berisi informasi gambar yang dihasilkan.

Properti

image string

URL gambar yang dihasilkan dalam format PNG. Tautan ini berlaku selama 24 jam. Harap segera unduh dan simpan gambarnya.

usage object

Penggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil.

Properti

output_width integer

Lebar gambar output akhir dalam piksel.

output_height integer

Tinggi gambar output akhir dalam piksel.

input_image_count integer

Jumlah gambar input dalam permintaan. Mengembalikan 0 untuk teks-ke-gambar (T2I), dan jumlah aktual untuk gambar-ke-gambar (I2I).

input_image_type string

Tingkat penagihan gambar input. Ditentukan berdasarkan area piksel resolusi output: qima_input_1k jika area ≤ 2.250.000, atau qima_input_2k jika area > 2.250.000.

output_image_count integer

Jumlah aktual gambar output yang dikembalikan.

output_image_type string

Tingkat penagihan gambar output. Ditentukan berdasarkan area piksel resolusi output: qima_output_1k jika area ≤ 2.250.000, atau qima_output_2k jika area > 2.250.000.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Berhasil

Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan.

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 1,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

Error

Jika tugas gagal, respons mencakup kode kesalahan dan pesan. Lihat Kode kesalahan untuk troubleshooting.

{
    "request_id": "31f808fd-8eef-9004-xxxxx",
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided."
}

SDK

Contoh berikut menunjukkan cara memanggil API menggunakan SDK Python dan Java untuk gambar-ke-gambar / pengeditan gambar (I2I).

import os
import base64
import mimetypes
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

# [Method 1] Use a public image URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"

# [Method 2] Use a Base64-encoded image
# image_url = encode_file("./your_image.png")

response = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-image-3.0-pro",
    messages=[{
        "role": "user",
        "content": [
            {"image": image_url},
            {"text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop."}
        ]
    }],
    prompt_extend=True
)

print(response)
if response.status_code == 200:
    url = response.output.choices[0].message.content[0]["image"]
    print(f"Generated image URL: {url}")
else:
    print(f"Error: {response.code} - {response.message}")
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;

public class ImageEditExample {
    public static void main(String[] args) {
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        // [Method 1] Use a public image URL
        String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";

        // [Method 2] Use a Base64-encoded image
        // String imageUrl = encodeFile("/path/to/your/image.png");

        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder()
            .role(Role.USER.getValue())
            .content(Arrays.asList(
                Collections.singletonMap("image", imageUrl),
                Collections.singletonMap("text", "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.")
            ))
            .build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model("qwen-image-3.0-pro")
            .messages(Arrays.asList(userMessage))
            .parameter("prompt_extend", true)
            .build();
        try {
            MultiModalConversationResult result = conv.call(param);
            System.out.println(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format");
        }
        byte[] fileBytes = null;
        try {
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }
        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }
}

API Asinkron

Selain panggilan sinkron yang dijelaskan di atas, Qwen Image Generation and Editing 3.0 juga mendukung panggilan asinkron. API asinkron memiliki struktur parameter permintaan yang sama dengan API sinkron. Anda hanya perlu menambahkan header X-DashScope-Async: enable. Setelah layanan menerima permintaan, layanan akan mengembalikan ID tugas (task_id), yang kemudian Anda gunakan untuk melakukan polling ke API kueri guna mendapatkan hasil akhir.

PentingTitik akhir untuk API asinkron berbeda dari API sinkron. Gunakan titik akhir dalam bagian ini, bukan titik akhir sinkron.

HTTP

Panggilan asinkron menggunakan alur kerja dua langkah:

  1. Buat tugas untuk mendapatkan ID tugas: Kirim permintaan untuk membuat tugas. Respons berisi ID tugas (task_id).
  2. Lakukan polling hasil menggunakan ID tugas: Gunakan task_id untuk memeriksa status tugas hingga tugas selesai dan URL gambar dikembalikan.

Langkah 1: Buat tugas untuk mendapatkan ID tugas

Singapura

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

China (Hong Kong)

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Jerman (Frankfurt)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Jepang (Tokyo)

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Parameter permintaan
Header

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

X-DashScope-Async string (Wajib)

Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus berupa enable.

PentingJika header permintaan ini tidak ada, error "current user api does not support synchronous calls" akan dikembalikan.

Body permintaan

model string (Wajib)

Nama model. Nilai yang tersedia: qwen-image-3.0-pro dan qwen-image-3.0.

input object (Wajib)

Objek parameter input, yang berisi bidang-bidang berikut:

Properti

messages array (Wajib)

Array konten permintaan. Hanya percakapan satu putaran yang didukung, sehingga array harus berisi tepat satu objek dengan properti role dan content.

Properti

rolestring (Wajib)

Peran pengirim pesan. Harus diatur ke user.

contentarray (Wajib)

Array konten pesan, dengan kombinasi berbeda tergantung kasus penggunaan:

  • Teks-ke-gambar (T2I): Hanya berisi satu objek {"text": "..."}.
  • Gambar-ke-gambar (I2I): Berisi 1–3 objek {"image": "..."} dan 1 objek {"text": "..."}.

Properti

image string (Wajib untuk I2I)

URL atau data terenkripsi Base64 dari gambar input. Dalam skenario I2I, 1–3 gambar didukung. Saat beberapa gambar disediakan, urutannya ditentukan oleh urutan array.

Persyaratan gambar:
  • Format gambar: JPG, JPEG, PNG, BMP, TIFF, WEBP, dan GIF.
  • Resolusi gambar: Lebar dan tinggi sebaiknya antara 384 hingga 2048 piksel untuk hasil terbaik.
  • Ukuran gambar: Maksimal 10 MB.
Format input yang didukung
  1. URL publik: Protokol HTTP dan HTTPS didukung.
  2. Pengkodean Base64: Formatnya adalah data:{MIME_type};base64,{base64_data}.

textstring(Wajib)

Prompt positif yang menjelaskan konten, gaya, dan pencampuran aliran gambar yang ingin Anda hasilkan atau edit. Bahasa Tionghoa dan Inggris didukung. Maksimum yang direkomendasikan: 4.500 token.

Catatan: Hanya satu objek teks yang diizinkan. Menghilangkannya atau menyediakan beberapa objek teks akan menghasilkan error.

parameters object (Opsional)

Parameter tambahan untuk mengontrol pembuatan gambar.

Properti

prompt_extend boolean (Opsional)

Apakah akan mengaktifkan penulisan ulang prompt cerdas. Bawaan: true (direkomendasikan). Saat diaktifkan, model mengoptimalkan prompt positif menggunakan metode yang ditentukan oleh prompt_extend_mode, yang secara signifikan meningkatkan hasil untuk deskripsi sederhana.

prompt_extend_mode string (Opsional)

Metode penulisan ulang prompt. Bawaan: direct. Opsi:

  • direct: Direct Prompt Enhancement (DPE), cocok untuk sebagian besar skenario. Didukung untuk T2I dan I2I.
  • agent: Agent Prompt Enhancement (APE), memberikan penulisan ulang yang lebih rinci. Hanya mendukung teks-ke-gambar (T2I). Memberikan agent untuk gambar-ke-gambar (I2I) akan mengembalikan error 400.

enable_thinking boolean (Opsional)

Mengaktifkan mode berpikir. Bawaannya adalah true. Ini meningkatkan penalaran model untuk memperbaiki kualitas gambar, tetapi memperpanjang waktu pembuatan. Memerlukan prompt_extend=true. Didukung untuk Direct T2I, Direct I2I, dan Agent T2I. Tidak didukung untuk I2I Agent.

n integer (Opsional)

Jumlah gambar output. Rentang nilai: 1 hingga 6. Bawaan: 1.

size string (Opsional)

Resolusi gambar output dalam format width*height, misalnya "1024*1024". Jika tidak ditentukan, model secara otomatis merekomendasikan resolusi berdasarkan prompt.

  • Teks-ke-gambar (T2I): Area piksel dari 512512 hingga 20482048. Rasio aspek: 1:8 hingga 8:1.
  • Gambar-ke-gambar (I2I): Area piksel dari 512512 hingga 20482048. Rasio aspek: 1:8 hingga 8:1.

negative_prompt string (Opsional)

Prompt negatif yang menjelaskan konten yang tidak ingin muncul dalam gambar.

seed integer (Opsional)

Seed acak. Rentang nilai: [0, 2147483647]. Jika dihilangkan, layanan menghasilkan seed acak. Gunakan seed tetap untuk hasil yang dapat direproduksi.

watermark boolean (Opsional)

Apakah akan menambahkan Watermark. Bawaan: false.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads '\''Il Messaggero'\'' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street'\''s end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
Parameter respons

output object

Informasi penerimaan tugas.

Properti

task_id string

ID tugas asinkron, digunakan untuk menanyakan status dan hasil tugas. Pastikan untuk menyimpannya.

task_status string

Status tugas. Biasanya PENDING saat tugas diajukan, yang hanya menunjukkan bahwa tugas telah diterima, bukan bahwa gambar telah dihasilkan.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Respons berhasil

Simpan task_id untuk menanyakan status tugas dan hasilnya.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Respons error

Pembuatan tugas gagal. Lihat Kode kesalahan.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Langkah 2: Lakukan polling hasil menggunakan ID tugas

Singapura

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

China (Hong Kong)

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}

Jerman (Frankfurt)

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Jepang (Tokyo)

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Anda harus menggunakan wilayah, ruang kerja, dan Kunci API yang sama seperti saat membuat tugas. Kueri lintas-wilayah atau lintas-ruang kerja tidak didukung.

Parameter permintaan
Header

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Parameter path URL

task_id string (Wajib)

ID tugas tersebut.

Kueri hasil tugas

Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Parameter respons

output object

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
Transisi status selama polling:
  • PENDING → RUNNING → SUCCEEDED atau FAILED.
  • Status kueri awal biasanya PENDING atau RUNNING.
  • Saat status berubah menjadi SUCCEEDED, respons berisi URL gambar yang dihasilkan.
  • Jika statusnya FAILED, periksa pesan error dan coba ulang tugas tersebut.

submit_time string

Waktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Waktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Waktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

rewrite_status string

Status penulisan ulang prompt. Nilainya bergantung pada apakah penulisan ulang diaktifkan dalam permintaan dan hasil penulisannya.

choices array

Daftar opsi hasil.

Properti

finish_reason string

Alasan tugas dihentikan. Nilainya adalah stop saat tugas selesai secara normal.

message object

Pesan yang dikembalikan oleh model.

Properti

rolestring

Peran pesan. Tetap sebagai assistant.

contentarray

Konten pesan yang berisi informasi gambar yang dihasilkan.

Properti

image string

URL gambar yang dihasilkan dalam format PNG. Tautan ini berlaku selama 24 jam. Harap segera unduh dan simpan gambarnya.

usage object

Penggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil.

Properti

output_width integer

Lebar gambar output akhir dalam piksel.

output_height integer

Tinggi gambar output akhir dalam piksel.

input_image_count integer

Jumlah gambar input dalam permintaan. Mengembalikan 0 untuk teks-ke-gambar (T2I), dan jumlah aktual untuk gambar-ke-gambar (I2I).

input_image_type string

Tingkat penagihan gambar input. Ditentukan berdasarkan area piksel resolusi output: qima_input_1k jika area ≤ 2.250.000, atau qima_input_2k jika area > 2.250.000.

output_image_count integer

Jumlah aktual gambar output yang dikembalikan.

output_image_type string

Tingkat penagihan gambar output. Ditentukan berdasarkan area piksel resolusi output: qima_output_1k jika area ≤ 2.250.000, atau qima_output_2k jika area > 2.250.000.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Tugas berhasil

Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan.

{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-07 15:50:14.837",
        "scheduled_time": "2026-08-07 15:50:14.884",
        "end_time": "2026-08-07 15:50:33.607",
        "rewrite_status": "not_use",
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
}

Tugas gagal

Jika tugas gagal, task_status bernilai FAILED dengan kode kesalahan dan pesan. Lihat Kode kesalahan.

{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "An internal error has occurred."
    },
    "request_id": "31f808fd-8eef-9004-xxxxx"
}

Kode kesalahan

Jika panggilan model gagal dan mengembalikan pesan error, lihat Kode kesalahan untuk penyelesaian.