Alibaba Cloud Model Studio:Referensi API Qwen-Image

Qwen-Image adalah model generasi gambar serbaguna yang mendukung berbagai gaya artistik dan unggul dalam complex text rendering . Model ini menangani tata letak multi-baris, generasi teks tingkat paragraf, dan rendering detail halus.

Contoh

Ikhtisar model

Prasyarat

Sebelum melakukan panggilan, dapatkan Kunci API dan ekspor Kunci API sebagai variabel lingkungan. Untuk melakukan panggilan menggunakan SDK, instal SDK DashScope.

API Sinkron

HTTP

Panggilan sinkron mengembalikan hasil dalam satu permintaan.

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

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

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-2.0-pro",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
            }
          ]
        }
      ]
    },
    "parameters": {
      "negative_prompt": "Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
      "prompt_extend": true,
      "watermark": false,
      "size": "2048*2048"
    }
}'

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 2048,
        "image_count": 1,
        "width": 2048
    },
    "request_id": "d0250a3d-b07f-49e1-bdc8-6793f4929xxx"
}

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

Panggilan SDK DashScope

SDK DashScope mendukung Python dan Java.

Nama parameter dalam SDK sangat mirip dengan parameter HTTP, dan struktur parameter mengikuti konvensi khas bahasa pemrograman. Untuk parameter panggilan sinkron, lihat HTTP.

import json
import os
import dashscope
from dashscope import MultiModalConversation

# Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda berdasarkan wilayah.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

messages = [
    {
        "role": "user",
        "content": [
            {"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
        ]
    }
]

# Kunci API berbeda antara wilayah Beijing dan Singapura. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika Anda belum mengatur variabel lingkungan, ganti baris di bawah ini dengan: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-2.0-pro",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    negative_prompt="Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
    size='2048*2048'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
else:
    print(f"Kode status HTTP: {response.status_code}")
    print(f"Kode kesalahan: {response.code}")
    print(f"Pesan kesalahan: {response.message}")
    print("Lihat dokumentasi: https://www.alibabacloud.com/help/en/model-studio/error-code")

{
    "status_code": 200,
    "request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    }
}

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.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class QwenImage {

    static {
        // Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda berdasarkan wilayah.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Kunci API berbeda antara wilayah Beijing dan Singapura. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // Jika Anda belum mengatur variabel lingkungan, ganti baris di bawah ini dengan: static String apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {

        MultiModalConversation conv = new MultiModalConversation();

        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("text", "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.")
                )).build();

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("watermark", false);
        parameters.put("prompt_extend", true);
        parameters.put("negative_prompt", "Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.");
        parameters.put("size", "2048*2048");

        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .apiKey(apiKey)
                .model("qwen-image-2.0-pro")
                .messages(Collections.singletonList(userMessage))
                .parameters(parameters)
                .build();

        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

{
    "requestId": "5b6f2d04-b019-40db-a5cc-xxxxxx",
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    }
}

Penggunaan dengan OpenAI Agents SDK

Model pembuatan gambar seperti Qwen-Image dipanggil melalui API native DashScope dan tidak mendukung mode kompatibel OpenAI (compatible-mode), sehingga tidak dapat digunakan secara langsung sebagai model penalaran suatu Agent dalam OpenAI Agents SDK.

Dalam kerangka kerja agent seperti OpenAI Agents SDK, Anda dapat membungkus pembuatan gambar sebagai tool (function tool) dan membiarkan model chat teks yang mendukung mode kompatibel OpenAI (misalnya qwen-plus) bertindak sebagai inti penalaran Agent untuk mengoordinasikannya. Contohnya:

Sebelum menjalankan, instal dependensi: pip install openai-agents dashscope.

import os
import asyncio
import dashscope
from openai import AsyncOpenAI
from dashscope import MultiModalConversation
from agents import Agent, Runner, function_tool, OpenAIChatCompletionsModel

# Baca Kunci API Model Studio dari variabel lingkungan
# (atau ganti dengan api_key="sk-xxx")
API_KEY = os.getenv("DASHSCOPE_API_KEY")

# Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya. URL berbeda-beda tergantung wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Model chat teks (inti penalaran Agent) diakses melalui mode kompatibel OpenAI
client = AsyncOpenAI(api_key=API_KEY, base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")

# Bungkus pembuatan gambar sebagai function tool agar dapat dipanggil oleh Agent
@function_tool
def generate_image(prompt: str) -> str:
    """Generate an image from a text description and return its URL. prompt: the text description of the image."""
    rsp = MultiModalConversation.call(
        api_key=API_KEY,
        model="qwen-image-2.0-pro",
        messages=[{"role": "user", "content": [{"text": prompt}]}],
        result_format="message",
    )
    if rsp.status_code != 200:
        return f"Generation failed: {rsp.code} {rsp.message}"
    return rsp.output.choices[0].message.content[0]["image"]

agent = Agent(
    name="Image Assistant",
    instructions="You are an image generation assistant. When the user wants an image, call the generate_image tool and return the image URL to the user.",
    model=OpenAIChatCompletionsModel(model="qwen-plus", openai_client=client),
    tools=[generate_image],
)

async def main():
    result = await Runner.run(agent, "Draw a corgi running on the grass")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Billing and rate limiting

• Untuk kuota gratis dan informasi harga, lihat Model pricing.
• Untuk batas laju (rate limits), lihat Qwen-Image.
• Detail Tagihan: Setiap successfully generated image akan dikenai biaya. Panggilan yang gagal atau error pemrosesan tidak dikenai biaya maupun mengurangi new user free quota Anda.

Kode error

Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Kode error untuk resolusi.

FAQ

T: Haruskah saya mengaktifkan atau menonaktifkan parameter prompt_extend?

J: Aktifkan opsi ini (default) jika Anda menginginkan konten gambar yang lebih beragam dan agar model menambahkan detail. Nonaktifkan jika Anda memerlukan kontrol yang lebih ketat terhadap detail gambar, dan optimalkan prompt Anda menggunakan Text-to-Image Prompt Guide.

T: Apa perbedaan antara model seri qwen-image-2.0?

J:

• Model gabungan untuk pembuatan dan pengeditan gambar: Mendukung teks-ke-gambar dan Pengeditan gambar.

  • qwen-image-2.0-pro dan qwen-image-2.0-pro-2026-03-03: Kemampuan sama. Seri Pro memberikan rendering teks yang lebih profesional, tekstur realistis yang lebih halus, adegan realistis yang lebih detail, serta kepatuhan semantik yang lebih kuat. Hanya mendukung panggilan sinkron.
  • qwen-image-2.0 dan qwen-image-2.0-2026-03-03: Kemampuan sama. Versi akselerasi ini menyeimbangkan kinerja dan kualitas model. Hanya mendukung panggilan sinkron.

T: Bagaimana cara mendapatkan daftar putih nama domain untuk penyimpanan gambar?

J: Gambar yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik temporary. Untuk mengonfigurasi daftar putih firewall untuk URL unduh ini, perhatikan hal berikut: Penyimpanan dasar dapat berubah secara dinamis. Topik ini tidak menyediakan daftar putih Nama domain OSS tetap untuk mencegah masalah akses akibat informasi yang kedaluwarsa. Jika Anda memiliki persyaratan kontrol keamanan, hubungi account manager Anda untuk mendapatkan daftar Nama domain OSS terbaru.