Skip to main content

Référence de l'API Qwen-Image

Qwen-Image est un modèle de génération d'images polyvalent qui prend en charge plusieurs styles artistiques et excelle dans le rendu de texte complexe . Il gère les mises en page multilignes, la génération de texte au niveau des paragraphes ainsi que le rendu précis des détails.

Accès rapide : Guide utilisateur

Essayer en ligne(Singapore

Beijing)**

** Blog technique (plus d'exemples)

Exemples

Prompt

Image générée

A 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!” appears prominently 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.

image

Présentation des modèles

ModèleDescriptionSpécifications des images en sortie
qwen-image-2.0-pro Recommandé
Mêmes capacités que qwen-image-2.0-pro-2026-04-22
Série Qwen Pro dédiée à la génération et à l'édition d'images. Elle offre un rendu de texte amélioré, des textures réalistes et une meilleure adhérence sémantique.
Pour l'édition d'images, consultez Édition avec Qwen-Image.
Résolution : la largeur et la hauteur sont configurables librement. Le nombre total de pixels doit se situer entre 512×512 et 2048×2048. La résolution par défaut est de 2048×2048.Format : PNGNombre d'images : 1 à 6
qwen-image-2.0-pro-2026-06-22 Recommandé
qwen-image-2.0-pro-2026-04-22
qwen-image-2.0-pro-2026-03-03
qwen-image-2.0 Recommandé
Mêmes capacités que qwen-image-2.0-2026-03-03
Série accélérée Qwen pour la génération et l'édition d'images. Elle assure un équilibre entre qualité et rapidité de réponse.
Pour l'édition d'images, consultez Édition avec Qwen-Image.
qwen-image-2.0-2026-03-03 Recommandé
Avant d'appeler l'API, vérifiez la liste des modèles pris en charge pour votre région.

Prérequis

Avant tout appel, obtenez une clé API et exportez-la sous forme de variable d'environnement. Pour effectuer des appels via le SDK, installez le SDK DashScope.
Les régions China (Beijing) et Singapore disposent de clés API et d'endpoints de requête distincts. Ces éléments ne sont pas interchangeables. Tout appel interrégional entraîne des échecs d'authentification ou des erreurs de service.

API synchrone

HTTP

Les appels synchrones retournent les résultats dans une requête unique. Singapour :POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Pékin :POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Paramètres de la requête

  • Text-to-image
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"
    }
}'
En-têtes de la requête
Content-Type string (Obligatoire)Type de contenu de la requête. Doit être défini à application/json.
Authorization string (Obligatoire)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.
Corps de la requête
model string (obligatoire)Nom du modèle. Exemple : qwen-image-2.0-pro.
input object (obligatoire)Informations d'entrée.

Propriétés

messages array (obligatoire)Tableau d'objets message. Seules les conversations à tour unique sont prises en charge, ce tableau doit donc contenir exactement un élément.

Propriétés

rolestring (obligatoire)Rôle du message. Définissez cette valeur à user.contentarray (obligatoire)Tableau d'objets de contenu de message.

Propriétés

textstring(obligatoire)Prompt positif décrivant le contenu, le style et la composition souhaités pour l'image.Prend en charge le chinois et l'anglais. La série qwen-image-2.0 accepte jusqu'à 1 300 tokens. Les autres modèles acceptent jusqu'à 800 tokens. Le système tronque automatiquement les tokens excédentaires.Remarque : Un seul champ texte est autorisé. Son omission ou la fourniture de plusieurs champs entraîne une erreur.
parameters object (facultatif)Paramètres de traitement de l'image.

Propriétés

negative_prompt string (facultatif)Prompt négatif décrivant les éléments à exclure de l'image.Prend en charge le chinois et l'anglais. La longueur maximale est de 500 caractères. Les caractères excédentaires sont tronqués automatiquement.Exemple : Faible résolution, basse qualité, membres déformés, doigts mal formés, couleurs sursaturées, aspect cireux, absence de détails faciaux, surfaces trop lisses, apparence générée par IA. Composition chaotique. Texte flou ou déformé.size string (facultatif)Résolution de l'image de sortie, au format width*height.Modèles de la série qwen-image-2.0 : Le nombre total de pixels doit être compris entre 512×512 et 2048×2048. La résolution par défaut est 2048×2048. Résolutions recommandées :
  • 2688*1536 : 16:9
  • 1536*2688 : 9:16
  • 2048*2048 (par défaut) : 1:1
  • 2368*1728 : 4:3
  • 1728*2368 : 3:4
n integer (facultatif)Nombre d'images de sortie. La valeur par défaut est 1.Pour les modèles de la série qwen-image-2.0, vous pouvez choisir entre 1 et 6 images.prompt_extend bool (facultatif)Active la réécriture intelligente du prompt. Le modèle optimise le prompt positif sans affecter le prompt négatif.
  • true : Valeur par défaut. Active la réécriture. Privilégiez cette option pour diversifier le contenu de l'image ; le modèle ajoute alors des détails.
  • false : Désactive la réécriture. Utilisez cette option pour un contrôle plus précis des détails de l'image. Pour obtenir de meilleurs résultats, optimisez vos prompts en suivant le Guide des prompts Text-to-image.
Prompt original (orig_prompt) : Un chat roux assis avec une expression joyeuse, vif, adorable et incroyablement réaliste.Prompt réel (actual_prompt) : Portrait animalier photoréaliste : un chat roux assis au pelage fourni et doré par le soleil, arborant une expression vibrante et joyeuse, les yeux pétillants de curiosité et de chaleur. La tête légèrement inclinée, les oreilles dressées, la bouche entrouverte dans une pose vive et satisfaite, il dégage un charme adorable et un réalisme saisissant. Un éclairage naturel doux sublime la texture de chaque moustache et brin de fourrure, avec des reflets subtils sur le museau et l'intérieur des oreilles. Arrière-plan : un jardin d'automne doucement flouté à l'heure dorée, aux tons chauds de feuilles ambrées, parsemé de rayons de soleil filtrant à travers les arbres et laissant deviner quelques marches en pierre moussue. La composition place le chat au centre, nettement mis au point avec une faible profondeur de champ. Style : photographie ultra-réaliste, niveau de détail National Geographic, résolution 8K, Canon EOS R5, ouverture f/1.2, éclairage cinématographique, étalonnage fidèle à la réalité, post-traitement minimal. Aucun texte ni superposition.
watermark bool (facultatif)Ajoute un filigrane « Qwen-Image » dans le coin inférieur droit de l'image. Valeur par défaut : false. Style du filigrane : 1seed integer (facultatif)Graine de nombre aléatoire. Plage valide : [0,2147483647].L'utilisation de la même seed produit des résultats similaires. Si ce paramètre est omis, l'algorithme utilise une graine aléatoire.Remarque : La génération d'images étant probabiliste, les résultats peuvent varier même avec une seed identique.

Paramètres de la réponse

  • Tâche réussie
  • Échec de la tâche
Les URL des images ne sont valides que pendant 24 heures avant d'être automatiquement supprimées. Enregistrez rapidement les images générées.
{
    "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"
}
output objectInformations de sortie de la tâche.

Propriétés

choices arraySortie du modèle. Ce tableau contient exactement un élément.

Propriétés

finish_reason stringRaison de l'arrêt de la tâche. La valeur est stop pour les arrêts normaux.message objectMessage de réponse du modèle.

Propriétés

rolestringRôle du message. Valeur fixe : assistant.contentarray

Propriétés

image stringURL de l'image générée (format PNG). Expire après 24 heures. Téléchargez-la et enregistrez-la sans tarder.
task_metric objectStatistiques des résultats de la tâche. Non retourné pour les modèles de la série qwen-image-2.0.

Propriétés

TOTAL integerNombre total de tâches.SUCCEEDED integerNombre de tâches réussies.FAILED integerNombre de tâches ayant échoué.
usage object
Les appels SDK ImageSynthesis synchrones ne retournent pas ce champ.
Statistiques de sortie. Comptabilise uniquement les résultats réussis.

Propriétés

image_count integerNombre d'images générées. Pour les modèles de la série qwen-image-2.0, cette valeur correspond au paramètre n demandé (1–6).width integerLargeur de l'image générée, en pixels.height integerHauteur de l'image générée, en pixels.
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage.
code stringCode d'erreur. Retourné uniquement en cas d'échec de la requête. Consultez la rubrique Codes d'erreur.
message stringMessage d'erreur détaillé. Retourné uniquement en cas d'échec de la requête. Consultez la rubrique Codes d'erreur.

Appel via le SDK DashScope

Le SDK DashScope prend en charge Python et Java. Les noms des paramètres du SDK correspondent étroitement à ceux de l'API HTTP, et leur structure suit les conventions propres à chaque langage. Pour les paramètres d'appel synchrone, reportez-vous à la section HTTP.
  • Python
  • Java
Installez la dernière version du SDK DashScope pour Python afin d'éviter les erreurs d'exécution : Installer le SDK.
Exemple de requête
import json
import os
import dashscope
from dashscope import MultiModalConversation

# Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
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."}
        ]
    }
]

# API keys differ between Beijing and Singapore regions. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you haven't set the environment variable, replace the line below with: 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"HTTP status code: {response.status_code}")
    print(f"Error code: {response.code}")
    print(f"Error message: {response.message}")
    print("See documentation: https://www.alibabacloud.com/help/en/model-studio/error-code")
Exemple de réponse
Les URL des images expirent après 24 heures. Téléchargez les images sans tarder.
{
    "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"
                        }
                    ]
                }
            }
        ]
    }
}

Utilisation avec le SDK OpenAI Agents

Les modèles de génération d'images tels que Qwen-Image s'appellent via l'API native DashScope et ne prennent pas en charge le mode compatible OpenAI (compatible-mode). Ils ne peuvent donc pas servir directement de modèle de raisonnement pour un Agent dans le SDK OpenAI Agents. Dans les frameworks d'agents comme le SDK OpenAI Agents, vous pouvez encapsuler la génération d'images sous forme d'outil (function tool). Un modèle de chat textuel prenant en charge le mode compatible OpenAI (tel que qwen-plus) agit alors comme noyau de raisonnement de l'Agent pour orchestrer cet outil. Par exemple : Avant l'exécution, installez les dépendances : 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

# Read the Model Studio API Key from an environment variable
# (or replace with api_key="sk-xxx")
API_KEY = os.getenv("DASHSCOPE_API_KEY")

# Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# The text chat model (the Agent's reasoning core) is accessed via OpenAI-compatible mode
client = AsyncOpenAI(api_key=API_KEY, base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")

# Wrap image generation as a function tool for the Agent to call
@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())

Facturation et limitations de débit

  • Pour les quotas gratuits et les tarifs, consultez Tarification des modèles.
  • Concernant les limites de débit, reportez-vous à Qwen-Image.
  • Détails de facturation : chaque image générée avec succès est facturée. Les appels échoués ou les erreurs de traitement n'entraînent aucun frais et ne consomment pas votre quota gratuit nouvel utilisateur.

Codes d'erreur

Si l'appel du modèle échoue et renvoie un message d'erreur, consultez la rubrique Codes d'erreur pour résoudre le problème.

FAQ

Q : Faut-il activer ou désactiver le paramètre prompt_extend ?

R : Activez cette option (par défaut) si vous souhaitez un contenu d'image plus varié et laisser le modèle ajouter des détails. Désactivez-la si vous avez besoin d'un contrôle précis sur les détails de l'image ; dans ce cas, optimisez vos prompts à l'aide du Guide des prompts texte-vers-image.

Q : Quelles sont les différences entre les modèles de la série qwen-image-2.0 ?

R :
  • Modèles combinés de génération et d'édition d'images : prennent en charge à la fois la génération d'images à partir de texte et l'édition d'images.
    • qwen-image-2.0-pro et qwen-image-2.0-pro-2026-03-03 : capacités identiques. La série Pro offre un rendu de texte plus professionnel, des textures réalistes plus fines, des scènes réalistes détaillées et une meilleure adhérence sémantique. Prend uniquement en charge les appels synchrones.
    • qwen-image-2.0 et qwen-image-2.0-2026-03-03 : capacités identiques. Cette version accélérée offre un équilibre entre performances du modèle et qualité. Prend uniquement en charge les appels synchrones.

Q : Comment obtenir la liste d'autorisation de noms de domaine pour le stockage des images ?

R : Les images générées par les modèles sont stockées dans OSS. L'API renvoie une URL publique temporaire. Pour configurer une liste d'autorisation de pare-feu pour cette URL de téléchargement, notez ce qui suit : le stockage sous-jacent peut changer dynamiquement. Cette rubrique ne fournit pas de liste d'autorisation fixe de noms de domaine OSS afin d'éviter les problèmes d'accès causés par des informations obsolètes. Si vous avez des exigences en matière de contrôle de sécurité, contactez votre gestionnaire de compte pour obtenir la dernière liste de noms de domaine OSS.