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:
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.comkehttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapura: dari
https://dashscope-intl.aliyuncs.comkehttps://{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 permintaanHeaderContent-Type Tipe konten permintaan. Harus berupa Authorization Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx. Body permintaanmodel Nama model. Nilai yang tersedia: input Objek parameter input, yang berisi bidang-bidang berikut: parameters Parameter tambahan untuk mengontrol pembuatan gambar. | |
Parameter responsoutput Berisi hasil generasi model. usage Penggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil. request_id Identifier permintaan unik untuk pelacakan dan troubleshooting. code Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. message Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. | BerhasilData tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan. ErrorJika tugas gagal, respons mencakup kode kesalahan dan pesan. Lihat Kode kesalahan untuk troubleshooting. |
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:
- Buat tugas untuk mendapatkan ID tugas: Kirim permintaan untuk membuat tugas. Respons berisi ID tugas (task_id).
- 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 permintaanHeaderContent-Type Tipe konten permintaan. Harus berupa Authorization Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx. X-DashScope-Async Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus berupa PentingJika header permintaan ini tidak ada, error "current user api does not support synchronous calls" akan dikembalikan. Body permintaanmodel Nama model. Nilai yang tersedia: input Objek parameter input, yang berisi bidang-bidang berikut: parameters Parameter tambahan untuk mengontrol pembuatan gambar. | |
Parameter responsoutput Informasi penerimaan tugas. request_id Identifier permintaan unik untuk pelacakan dan troubleshooting. code Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. | Respons berhasilSimpan Respons errorPembuatan tugas gagal. Lihat Kode kesalahan. |
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 permintaanHeaderAuthorization Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx. Parameter path URLtask_id ID tugas tersebut. | Kueri hasil tugasGanti |
Parameter responsoutput Informasi output tugas. usage Penggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil. request_id Identifier permintaan unik untuk pelacakan dan troubleshooting. code Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. message Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. | Tugas berhasilData tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan. Tugas gagalJika tugas gagal, |
Kode kesalahan
Jika panggilan model gagal dan mengembalikan pesan error, lihat Kode kesalahan untuk penyelesaian.