Comment utiliser Postman ou cURL pour effectuer des requêtes HTTP - Alibaba Cloud Model Studio

Cette rubrique explique comment utiliser Postman et cURL pour appeler les API de génération d'images ou de vidéos sur Alibaba Cloud Model Studio (Bailian). Ce guide s'appuie sur un exemple de texte vers image pour illustrer le processus complet, de la création d'une tâche à la récupération du résultat.

Postman : outil graphique intuitif pour tester les requêtes HTTP. Recommandé pour les débutants.
cURL : outil puissant en ligne de commande destiné aux développeurs à l'aise avec le terminal.

RemarquePostman et cURL servent à réaliser des tests rapides et des vérifications fonctionnelles. Pour les environnements de production, utilisez les SDK officiels ou implémentez vos propres appels HTTP.

Mécanisme d'appel asynchrone

Les tâches de génération d'images et de vidéos peuvent nécessiter un temps de traitement important, allant de plus de dix secondes à plusieurs minutes. Afin d'éviter les connexions HTTP prolongées et les délais d'attente, l'API repose sur un mécanisme d'appel asynchrone. Le processus se déroule en deux étapes :

Création d'une tâche : appelez l'API pour créer une tâche. Le service retourne de manière synchrone un ID de tâche (task_id).
Interrogation du résultat : utilisez l'ID de tâche pour interroger régulièrement son statut jusqu'à son achèvement, puis récupérez l'URL finale de l'image ou de la vidéo.

Exemple d'appel HTTP (texte vers image)

Méthode 1 : Utiliser Postman (recommandé)

Configurer Postman à partir de cURL

Lors de la conversion d'une commande cURL en requête Postman, les paramètres correspondent aux éléments suivants :

Paramètre cURL	Interface Postman	Description
`curl -X POST` ou `curl -X GET`	Liste déroulante de la méthode de requête	Définit la méthode de requête HTTP.
`https://<api-endpoint-url>`	Champ de saisie de l'URL	L'URL de l'endpoint de l'API.
`-H 'Key: Value'`	Onglet Headers	Configure les en-têtes de requête sous forme de paires clé-valeur.
`-d '{...}'`	Onglet Body	Configure le corps de la requête.

Prérequis

Avant d'appeler l'API, obtenez une clé API pour votre région et téléchargez Postman.

Étape 1 : Créer une tâche

Utilisez la commande cURL suivante pour configurer Postman.

L'URL de base ci-dessous correspond à la région Singapour. Vous devez utiliser l'URL de base correspondant à votre région.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

Dans Postman, cliquez sur le bouton new ou + pour créer une nouvelle requête, puis sélectionnez HTTP comme type de requête.
Dans la liste déroulante des méthodes de requête, sélectionnez POST et saisissez l'URL correspondant à la région de déploiement de votre modèle :
- Singapour : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis, en remplaçant WorkspaceId par votre véritable ID d'espace de travail, comme décrit dans Obtenir l'ID d'espace de travail.
- États-Unis (Virginie) : https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- Chine (Pékin) : https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Pour connaître les modèles pris en charge dans chaque région, consultez la console Model Studio. La région actuelle et le périmètre de déploiement du service reposent sur les relations de liaison système prédéfinies ; les combinaisons personnalisées ne sont pas prises en charge.
```
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
```

Cliquez sur l'onglet Headers et ajoutez les trois paires clé-valeur suivantes.

Clé	Valeur	Description	Dans Postman, sous l'onglet Headers, définissez X-DashScope-Async sur `enable`, Authorization sur `Bearer <your-api-key>` et Content-Type sur `application/json`.
X-DashScope-Async	enable	Active les appels asynchrones.
Authorization	Bearer sk-xxx (Remplacez sk-xxx par votre clé API)	Identifiant d'authentification.
Content-Type	application/json	Indique que le corps de la requête est au format JSON.

Configurez le corps de la requête :
- Cliquez sur l'onglet Body, sélectionnez le bouton radio raw, choisissez JSON dans la liste déroulante de format à droite, puis collez le contenu JSON situé après -d dans l'exemple cURL, dans le champ de saisie.
```
{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}
```
- (Facultatif) Cliquez sur Beautify sur le côté droit de la page pour formater le JSON et en faciliter la lecture.
Cliquez sur Send pour envoyer la requête et obtenir le task_id. Cet identifiant reste valide pendant 24 heures. Passé ce délai, il n'est plus possible d'interroger le résultat. Veillez donc à récupérer le résultat rapidement.
```
{
    "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
    "output": {
        "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
        "task_status": "PENDING"
    }
}
```

Étape 2 : Interroger le résultat par ID de tâche

Une fois l'ID de tâche obtenu, appelez l'endpoint d'interrogation pour récupérer le résultat final.

Singapour : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis, en remplaçant WorkspaceId par votre véritable ID d'espace de travail.
États-Unis (Virginie) : https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Chine (Pékin) : https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

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

Configurez la requête d'interrogation dans Postman :

Créez une nouvelle requête HTTP.
Définissez la méthode de requête sur GET.
Selon la région, saisissez l'URL d'interrogation et remplacez {task_id} dans l'URL par le véritable task_id obtenu à l'étape 1.
Sous l'onglet Headers, ajoutez l'en-tête Authorization en utilisant la même clé API qu'à l'étape 1.
Cliquez sur Send.

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/42442de9-917d-4c41-80a7-37fb7ad25ed2

Headers:
Cookie: acw_tc=896b2ccd-a0cd-40a8-a557-bb73cee5cf957...
Postman-Token: <calculated when request is sent>
Host: <calculated when request is sent>
User-Agent: PostmanRuntime/7.49.1
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Authorization: Bearer sk-xxx

Vérifiez la réponse. Interrogez cet endpoint jusqu'à ce que le task_status passe à SUCCEEDED afin d'obtenir l'URL de l'image. Cette URL reste valide pendant 24 heures. Assurez-vous de télécharger l'image durant cette période de validité.

"results": [
            {
                "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
                "actual_prompt": "A cozy and elegant flower shop, with an exterior decorated with exquisitely carved windows. The window frames are light-colored wood, set with transparent glass that reveals the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate, giving it a quaint and textured feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including roses, lilies, hydrangeas, and tulips—are arranged in a staggered, vibrant display. Some bouquets are wrapped in kraft paper and tied with twine, exuding a fresh, natural scent. The background features a quiet European town streetscape, with stone-paved roads and greenery adding to the charm. The overall image is in a realistic photographic style, with soft lighting and a warm color palette that highlights the shop's exquisite and romantic atmosphere.",
                "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/3a/20251203/7a2bee47/42442de9-917d-4c41-80a7-37fb7ad25ed2.png?xxx"
            }
        ]

Méthode 2 : Utiliser cURL

Les développeurs familiers de la ligne de commande peuvent recourir à cURL pour tester rapidement l'API.

Prérequis

Avant d'exécuter la commande cURL :

Activez le service de modèle et obtenez une clé API.
Assurez-vous d'avoir installé cURL et configuré la clé API comme variable d'environnement afin de pouvoir référencer directement la variable $DASHSCOPE_API_KEY par la suite.
Vérifier si cURL est installé
Exécutez la commande suivante pour vérifier si cURL est installé.
```
curl --version
```
Si vous obtenez une sortie similaire à celle-ci, cURL est bien installé :
```
curl 8.x.x (x86_64-apple-darwin23.0) libcurl/8.x.x (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.58.0
Release-Date: 2023-10-11
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL threadsafe UnixSockets
```
En l'absence d'installation, un message semblable à l'un des suivants peut s'afficher :
- Windows : 'curl' is not recognized as an internal or external command, operable program or batch file.
- Linux/macOS : command not found: curl.
Rendez-vous sur la page de téléchargement de curl pour procéder à l'installation.

Étape 1 : Créer une tâche

Exécutez la commande suivante dans votre terminal :

L'URL de base ci-dessous correspond à la région Singapour. Vous devez utiliser l'URL de base correspondant à votre région.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

Une requête réussie retourne un task_id. Cet identifiant reste valide pendant 24 heures et ne permet plus d'interroger le résultat une fois expiré. Veillez à récupérer le résultat rapidement.

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
{"request_id":"ca3b5224-bc60-4e47-80f4-2790040e9e55","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d318061c43","task_status":"PENDING"}}

Étape 2 : Interroger le résultat par ID de tâche

Remplacez {task_id} dans la commande ci-dessous par l'ID de tâche obtenu à l'étape 1, copiez la commande dans le terminal, puis exécutez-la.

L'URL de base ci-dessous correspond à la région Singapour. Vous devez utiliser l'URL de base correspondant à votre région.
```
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
```

Une fois la tâche terminée (le task_status passe à SUCCEEDED), la réponse contient l'URL de l'image. Cette URL reste valide pendant 24 heures. Téléchargez-la sans tarder.

Le traitement par le modèle prenant un certain temps (de quelques dizaines de secondes à plusieurs minutes), il peut être nécessaire d'interroger cette API à plusieurs reprises. Nous vous recommandons d'effectuer une requête toutes les 3 à 5 secondes jusqu'à ce que le task_status ne soit plus RUNNING .

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"24143559-9964-4898-8f9c-d968bba182b9","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d3f8061c43","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:19:18.293","scheduled_time":"2025-12-03 10:19:18.320","end_time":"2025-12-03 10:19:31.890","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A cozy, elegant flower shop. The exterior wall features exquisitely carved windows with dark brown wooden frames, and the glass is clean and bright, revealing the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate that exudes a strong artisanal feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including blooming roses, elegant hydrangeas, fresh daisies, and green eucalyptus leaves—are arranged in a staggered yet harmonious display. The background is a quiet European town streetscape, with a stone-paved road and a vine-covered neighboring wall enhancing the romantic atmosphere. The overall image is in a realistic photographic style, with soft, natural lighting that highlights the wood texture and floral details.","url":"https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/59/20251203/7a2bee47/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43.png?Expires=1764814771&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/8b108773-4e7d-4cd7-8c62-aad7a08d7769 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"0ee9ab8a-0ea4-9f0b-9cb0-41eaf24fd5e8","output":{"task_id":"8b108773-4e7d-4cd7-8c62-aad7a08d7769","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:50:24.253","scheduled_time":"2025-12-03 10:50:24.282","end_time":"2025-12-03 10:50:42.708","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A warm and elegant flower shop, with an exterior wall decorated with an exquisitely carved window. The window frame is dark brown solid wood, with clean and bright glass revealing the soft light inside. The front door is a beautiful wooden door crafted with a vintage distressed technique, its surface retaining the wood grain texture, complemented by a brass door handle and a small nameplate decoration, exuding a strong handmade feel. In front of the door, on the windowsill, and on both sides of the entrance, various flowers are arranged in a staggered fashion—pink and white roses, pale purple hydrangeas, bright yellow sunflowers, and green eucalyptus leaves—with soft and layered colors. The background is a quiet European-style street, with cobblestones and vine-covered neighboring walls adding a romantic atmosphere. The overall image is in a realistic photography style, with warm and natural lighting, highlighting the tranquility and beauty of the flower shop.","url":"https://dashscope-result-sgp.oss-ap-southeast-1.aliyuncs.com/1d/63/20251203/c3a8f0e2/24817593-8b108773-4e7d-4cd7-8c62-aad7a08d7769.png?Expires=1748416642&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}%

Étapes suivantes

Après avoir généré votre première image avec succès, vous pouvez explorer les options suivantes :

Approfondir les paramètres de l'API : consultez la documentation de l'API texte vers image pour découvrir d'autres paramètres.
Tester la génération vidéo : essayez l'API première image vers vidéo pour créer une vidéo.
Découvrir d'autres modèles : accédez à la console Model Studio pour voir tous les modèles d'images et de vidéos pris en charge par Alibaba Cloud Model Studio (Bailian).