> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Génération d’images Muse Image Ext > Générez une image WebP par requête à partir de texte ou de 9 images de référence au maximum. > [!NOTE] > > Cette API est asynchrone. Enregistrez l’identifiant de tâche après l’envoi, puis consultez `GET /v1/tasks/{task_id}` pour obtenir l’état et les résultats. Dans la réponse par défaut, l’identifiant se trouve dans `data[0].task_id`. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Idempotency-Key: ' \ --data '{ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={ "Authorization": "Bearer ", "Accept": "application/json", "Idempotency-Key": "" }, json={ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 } ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json", Accept: "application/json", "Idempotency-Key": "" }, body: JSON.stringify({ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 }) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## En-têtes de requête **Authorization** `string` *required* Utilisez une APIMart API Key sous la forme `Bearer `. L’envoi et les requêtes de suivi doivent être authentifiés avec la même identité utilisateur. **Idempotency-Key** `string` Fortement recommandé. Utilisez une nouvelle clé pour chaque génération indépendante (1–191 caractères ASCII visibles ; UUID recommandé). Remplacez `` dans les exemples. Après un délai d’attente dépassé ou une erreur réseau, conservez le même endpoint, corps, version de réponse et clé lors de la nouvelle tentative. Une fois l’identifiant reçu, consultez uniquement cette tâche. ## Paramètres de requête **model** `string` *required* Valeur fixe : `muse-image-ext`. **prompt** `string` *required* Description du contenu à générer, en chinois ou en anglais. Elle ne doit pas être vide après suppression des espaces en début et fin. Obligatoire même avec des images de référence. **image\_urls** `string[]` Jusqu’à 9 entrées d’images de référence non vides. Accepte les URL publiques, Data URI (par exemple `data:image/png;base64,...`) ou le base64 brut. Omettez ce champ ou envoyez `[]` pour générer uniquement à partir du texte. PNG, JPEG et WebP sont recommandés. Les URL doivent être directement accessibles au serveur sans cookies de connexion du navigateur. La taille d’origine cumulée de toutes les images ne doit pas dépasser **11 MiB (11 534 336 octets)**. Cette limite est globale, pas par image. Le base64 augmente aussi la taille du corps de requête. N’envoyez pas d’URL `blob:`, de chemins locaux ni d’objets `File`. **aspect\_ratio** `string` Accepte les sept ratios ci-dessous. Sans ce champ, la génération depuis du texte utilise `1:1` ; avec des références, elle suit leur composition. Un ratio explicite prévaut. Pour la sélection automatique, omettez le champ ; n’envoyez pas `"auto"`. `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` **size** `string` Champ de compatibilité acceptant les sept ratios ci-dessus ou `auto`, mais pas des dimensions en pixels comme `1024x1024`. Envoyer uniquement `size: "auto"` revient à ne pas définir de ratio. Préférez `aspect_ratio`. Si les deux valeurs sont valides, `aspect_ratio` prévaut, mais chaque champ est validé séparément : un ratio valide ne corrige pas un `size` invalide. **n** `integer` (default: 1) Un seul résultat par requête. Seul le nombre `1` est accepté. Une valeur explicite `0`, négative ou supérieure à `1` provoque une erreur. > [!NOTE] > > Renvoie une URL WebP. Le modèle détermine les dimensions ; les tailles en pixels et les niveaux 1K / 2K / 4K ne sont pas configurables. N’envoyez pas de `resolution` non vide ni de champs de durée. ### Autres paramètres facultatifs **webhook** `string` URL de base du backend recevant les notifications. La plateforme retire les barres obliques finales et ajoute `/callback` : `https://your-backend.example/muse` devient `https://your-backend.example/muse/callback`. Omettez ce champ si vous utilisez uniquement le suivi par requêtes. **language** `string` Langue des messages d’erreur du Webhook, sans effet sur le contenu généré. Valeurs : `zh`, `en`, `ja`, `ko`, `ru`, `fr`, `de`, `id`, `pt`, `es`. Les codes régionaux comme `zh-CN` ne sont pas acceptés. Pour le suivi, précisez la langue séparément dans la query string GET. ## Génération avec des images de référence ```json theme={null} { "model": "muse-image-ext", "prompt": "Keep the cup from the reference image and place it on a wooden cafe table in warm natural light", "image_urls": [ "https://your-cdn.example/cup.png" ], "n": 1 } ``` Remplacez l’URL d’exemple par une URL d’image accessible. Le ratio est omis pour suivre la composition de la référence ; ajoutez `aspect_ratio` pour imposer un ratio. Ajoutez les autres images à `image_urls`, jusqu’à 9 au total. ## Réponse à l’envoi La réponse par défaut est HTTP `200`, avec `data` sous forme de tableau. `submitted` signifie que la tâche est acceptée, pas terminée. Enregistrez `data[0].task_id`, puis consultez la tâche. > **Version de réponse facultative : 2026-07-27** > > Avec l’en-tête `X-APIMart-Response-Version: 2026-07-27`, l’envoi renvoie HTTP `202`. Lisez l’identifiant dans `data.id` et le chemin de suivi dans `data.poll_url`. > > ```json theme={null} > { > "code": 202, > "request_id": "req_example", > "data": { > "id": "task_01K...", > "object": "generation.task", > "type": "image", > "status": "pending", > "progress": 0, > "poll_url": "/v1/tasks/task_01K..." > } > } > ``` > > Cette version ne modifie pas la structure des réponses GET. Si vous ajoutez cet en-tête, ne continuez pas à lire l’identifiant d’envoi dans `data[0].task_id`. ## Consulter l’état et les résultats Utilisez l’identifiant complet reçu à l’envoi et la même identité utilisateur. `language` est facultatif et définit la langue des erreurs. Tous les champs figurent dans [État des tâches](https://docs.apimart.ai/fr/api-reference/tasks/status.md). ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/?language=fr' \ --header 'Authorization: Bearer ' ``` Interrogez toutes les 5 secondes, sans requêtes simultanées pour une même tâche. Un délai d’attente côté client ou l’arrêt du suivi n’annule pas la tâche serveur. Conservez l’identifiant et reprenez les requêtes GET plus tard ; ne relancez pas automatiquement une génération. | `data.status` | Action | | - | - | | `pending` / `processing` | En attente ou en cours ; poursuivre les requêtes de suivi. | | `completed` | Génération réussie ; arrêter le suivi et lire l’URL du résultat. | | `failed` | Échec de génération ; arrêter le suivi et lire `data.error.message`. | | `unknown` / … | État incertain. Conserver l’identifiant et limiter les nouvelles tentatives de consultation ; ne pas considérer la tâche comme réussie ni régénérer automatiquement. | Déterminez la fin à partir de `data.status`. HTTP `200` ou `progress: 100` ne suffit pas à indiquer une génération réussie. Un `polling_error` pendant le traitement n’est pas un échec terminal. Exemple de réponse pour une tâche terminée (URL de résultat fictive) : ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "images": [ { "url": [ "https://cdn.example/generated-image.webp" ] } ] } } } ``` Dans les réponses de suivi, `data` est un objet et `url` un tableau de chaînes. Le premier résultat se trouve dans `data.result.images[0].url[0]`. Si présent, `expires_at` indique l’expiration en secondes Unix ; sauvegardez les fichiers nécessaires avant cette date. `actual_time` mesure le temps de traitement, pas la durée de lecture vidéo. ## Limites et gestion des erreurs Les vidéos et audios de référence, masques, contrôles de première/dernière image, extensions et remix ne sont pas pris en charge. `quality` est sans effet. Omettez `seed`, `negative_prompt`, `width`, `height`, `response_format` et `output_format`, qui ne font pas partie des paramètres de génération de ce modèle. `async: false` n’active pas la génération synchrone et `stream` ne fournit pas de flux SSE de génération. | HTTP / `error.code` | Action | | - | - | | `400 / invalid_request_error` | Vérifier le prompt, le nombre de références, le ratio, le nombre de sorties et les spécifications fixes. | | `409 / idempotency_in_progress` | Attendre selon `Retry-After`, puis renvoyer la requête d’origine avec la même clé d’idempotence. | | `409 / idempotency_key_reused` | La même clé a été utilisée pour des requêtes différentes. Corriger la gestion des clés ; chaque génération indépendante nécessite une nouvelle clé. | | `409 / idempotency_result_indeterminate` | Arrêter les renvois automatiques et conserver la clé ainsi que les informations de tâche pour investigation. | | `429` | Attendre selon `Retry-After` avant de réessayer. | Une tâche échouée peut encore renvoyer HTTP `200` ; vérifiez `data.status` et `data.error.message`. Une erreur réseau ou `5xx` lors de l’envoi peut survenir après acceptation : ne renvoyez pas immédiatement avec une nouvelle clé. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.