Skip to main content

Référence de l'API Qwen Image Generation and Editing 3.0

Le modèle Qwen Image Generation and Editing 3.0 prend en charge la génération d'images à partir de texte (T2I) ainsi que l'édition d'images (I2I). Il génère des images directement depuis des invites textuelles ou modifie des images existantes en s'appuyant sur une à trois images de référence accompagnées d'instructions d'édition.

Présentation du modèle

ModèleDescriptionSpécifications des images générées
qwen-image-3.0-proModèle Qwen Image Generation and Editing 3.0 compatible avec la génération texte-vers-image (T2I) et l'édition image-vers-image (I2I).Résolution d'image :
  • Texte-vers-image (T2I) : Le nombre total de pixels doit se situer entre 512512 et 20482048.
  • Image-vers-image (I2I) : Le nombre total de pixels doit se situer entre 512512 et 20482048.
  • Par défaut : Si le paramètre size n'est pas spécifié, le modèle recommande automatiquement une résolution adaptée à l'invite.
Format d'image : PNG
qwen-image-3.0Modèle standard Qwen Image Generation and Editing 3.0 prenant en charge le T2I et l'I2I. Il offre un équilibre optimal entre qualité et rapidité.

Disponibilité

Le modèle, l'URL de l'endpoint et la clé API doivent appartenir à la même région. Les appels interrégionaux échouent systématiquement.
  • Sélectionner un modèle : Vérifiez que le modèle est disponible dans votre région cible.
  • Choisir une URL : Sélectionnez l'URL d'endpoint correspondant à la région de votre modèle. Les URL HTTP et DashScope SDK sont toutes deux prises en charge.
  • Configurer une clé API : Obtenez une clé API pour la région concernée, puis configurez-la comme variable d'environnement.
  • Installer le SDK : Pour appeler l'API via le SDK, installez le SDK DashScope.
Les exemples de code de cette rubrique s'appliquent à la région Singapour.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : de https://dashscope.aliyuncs.com vers https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de https://dashscope-intl.aliyuncs.com vers https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à l'ID de votre espace de travail, consultable sur la page Workspace Details de la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

HTTP

  • Singapore
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Remplacez {WorkspaceId} par votre ID d'espace de travail.

Paramètres de la requête

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
    }
}'
En-têtes
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. Valeurs disponibles : qwen-image-3.0-pro et qwen-image-3.0.
input object (Obligatoire)Objet contenant les paramètres d'entrée, composé des champs suivants :

Propriétés

messages array (Obligatoire)Tableau du contenu de la requête. Seules les conversations à tour unique sont prises en charge, ce tableau doit donc contenir exactement un objet doté des propriétés role et content.

Propriétés

rolestring (Obligatoire)Rôle de l'expéditeur du message. Doit être défini à user.contentarray (Obligatoire)Tableau du contenu du message, dont la combinaison varie selon le cas d'usage :
  • Texte-vers-image (T2I) : Contient uniquement un objet {"text": "..."}.
  • Image-vers-image (I2I) : Contient 1 à 3 objets {"image": "..."} ainsi qu'un objet {"text": "..."}.

Propriétés

image string (Obligatoire pour I2I)URL ou données encodées en Base64 de l'image d'entrée. Les scénarios I2I acceptent 1 à 3 images. En cas d'images multiples, leur ordre suit la séquence du tableau.Exigences relatives aux images :
  • Formats acceptés : JPG, JPEG, PNG, BMP, TIFF, WEBP et GIF.
  • Résolution : La largeur et la hauteur doivent idéalement se situer entre 384 et 2048 pixels pour un résultat optimal.
  • Taille maximale : 10 Mo.
Formats d'entrée pris en charge
  1. URL publique : Les protocoles HTTP et HTTPS sont pris en charge.
  2. Encodage Base64 : Le format attendu est data:{MIME_type};base64,{base64_data}.
textstring(Obligatoire)Invite positive décrivant le contenu, le style et la composition de l'image à générer ou modifier. Le chinois et l'anglais sont tous deux acceptés.Remarque : Un seul objet texte est autorisé. Son omission ou la présence de plusieurs objets texte entraînera une erreur.
parameters object (Facultatif)Paramètres supplémentaires permettant de contrôler la génération d'images.

Propriétés

prompt_extend boolean (Facultatif)Active ou désactive la réécriture intelligente des invites. Valeur par défaut : true (recommandé). Lorsque cette option est activée, le modèle optimise l'invite positive selon la méthode définie par prompt_extend_mode, ce qui améliore considérablement les résultats pour les descriptions simples.prompt_extend_mode string (Facultatif)Méthode de réécriture de l'invite. Valeur par défaut : direct. Options disponibles :
  • direct : Amélioration directe de l'invite (DPE), adaptée à la plupart des scénarios. Compatible T2I et I2I.
  • agent : Amélioration de l'invite par agent (APE), offrant une réécriture plus raffinée. Réservé au mode texte-vers-image (T2I). L'utilisation de agent en mode image-vers-image (I2I) renvoie une erreur 400.
n integer (Facultatif)Nombre d'images à générer. Plage de valeurs : 1 à 6. Valeur par défaut : 1.size string (Facultatif)Résolution de l'image de sortie au format largeur hauteur, par exemple "10241024". Sans spécification, le modèle recommande automatiquement une résolution adaptée à l'invite.
  • Texte-vers-image (T2I) : Surface en pixels comprise entre 512512 et 20482048. Ratio d'aspect : 1:8 à 8:1.
  • Image-vers-image (I2I) : Surface en pixels comprise entre 512512 et 20482048. Ratio d'aspect : 1:8 à 8:1.
negative_prompt string (Facultatif)Invite négative décrivant les éléments à exclure de l'image générée.seed integer (Facultatif)Graine aléatoire. Plage de valeurs : [0, 2147483647]. Une graine fixe permet d'obtenir des résultats relativement stables.watermark boolean (Facultatif)Ajoute ou non un filigrane. Valeur par défaut : false.

Paramètres de la réponse

  • Succès
  • Erreur
Les données de la tâche (statut et URL des images) ne sont conservées que pendant 24 heures avant d'être automatiquement supprimées. Pensez à enregistrer rapidement les images générées.
{
    "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"
}
output objectContient les résultats de la génération du modèle.

Propriétés

choices arrayListe des options de résultats.

Propriétés

finish_reason stringRaison de l'arrêt de la tâche. La valeur est stop lorsque la tâche se termine normalement.message objectMessage renvoyé par le modèle.

Propriétés

rolestringRôle associé au message. Valeur fixe : assistant.contentarrayContenu du message contenant les informations de l'image générée.

Propriétés

image stringURL de l'image générée au format PNG. Ce lien est valide pendant 24 heures. Téléchargez et enregistrez l'image sans tarder.
usage objectConsommation de ressources pour cet appel. Renvoyé uniquement en cas de succès.

Propriétés

output_width integerLargeur finale de l'image générée, en pixels.output_height integerHauteur finale de l'image générée, en pixels.input_image_count integerNombre d'images fournies en entrée. Renvoie 0 pour le mode texte-vers-image (T2I) et le compte réel pour le mode image-vers-image (I2I).input_image_type stringNiveau de facturation des images d'entrée. Déterminé par la surface en pixels de la résolution de sortie : qima_input_1k si la surface ≤ 2 250 000, ou qima_input_2k si la surface > 2 250 000.output_image_count integerNombre réel d'images générées et renvoyées.output_image_type stringNiveau de facturation des images de sortie. Déterminé par la surface en pixels de la résolution de sortie : qima_output_1k si la surface ≤ 2 250 000, ou qima_output_2k si la surface > 2 250 000.
request_id stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.
code stringCode d'erreur. Renvoyé uniquement en cas d'échec de la requête. Voir Codes d'erreur.
message stringMessage d'erreur détaillé. Renvoyé uniquement en cas d'échec de la requête. Voir Codes d'erreur.

SDK

Les exemples suivants illustrent l'appel de l'API via les SDK Python et Java pour l'édition d'images / image-vers-image (I2I).
Python
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}")

Codes d'erreur

Si l'appel au modèle échoue et renvoie un message d'erreur, consultez la rubrique Codes d'erreur pour obtenir une solution.