> ## 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 MiniMax-H3-Image > - Modèle standard minimax-h3-image, excellent en photo réaliste, affiches, visuels produit et images avec texte - Traitement asynchrone avec un task_id pour consulter le résultat - Texte vers image et retouche avec jusqu’à 16 images de référence - Jusqu’à 10 images par requête, optimisation du prompt intégrée (désactivable) - Niveaux 1K / 2K / 4K + format, ou dimensions exactes en pixels (20 mégapixels max.) ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "minimax-h3-image", "prompt": "Un café en bord de mer au crépuscule, style photo réaliste, tons chauds", "size": "16:9", "resolution": "2K", "n": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={ "Authorization": "Bearer ", "Content-Type": "application/json", }, json={ "model": "minimax-h3-image", "prompt": "Un café en bord de mer au crépuscule, style photo réaliste, tons chauds", "size": "16:9", "resolution": "2K", "n": 1, }, ) 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", }, body: JSON.stringify({ model: "minimax-h3-image", prompt: "Un café en bord de mer au crépuscule, style photo réaliste, tons chauds", size: "16:9", resolution: "2K", n: 1, }), }, ); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01KXXXXXXXXXXXXXXX" } ] } ``` ```json 400 theme={null} { "error": { "code": 400, "message": "Paramètres de requête invalides", "type": "invalid_request_error" } } ``` ```json 401 theme={null} { "error": { "code": 401, "message": "Échec de l’authentification. Vérifiez votre clé API.", "type": "authentication_error" } } ``` ```json 402 theme={null} { "error": { "code": 402, "message": "Solde du compte insuffisant", "type": "payment_required" } } ``` ```json 429 theme={null} { "error": { "code": 429, "message": "Trop de requêtes. Réessayez plus tard.", "type": "rate_limit_error" } } ``` ```json 500 theme={null} { "error": { "code": 500, "message": "Erreur interne du serveur. Réessayez plus tard.", "type": "server_error" } } ``` ## Authentification **Authorization** `string` *required* Tous les endpoints utilisent un Bearer Token. Obtenez votre clé sur la [page des clés API](https://apimart.ai/keys). ``` Authorization: Bearer YOUR_API_KEY ``` ## Présentation des modèles | Modèle | Caractéristiques | Utilisation recommandée | | - | - | - | | `minimax-h3-image` | Version standard, prix plus bas | Génération en lot, photo réaliste, affiches, visuels produit, images avec texte | | `minimax-h3-image-highspeed` | Version rapide : génération plus rapide, prix des images en entrée / sortie deux fois plus élevé que la version standard | Cas sensibles au temps de réponse ; voir [MiniMax-H3-Image-Highspeed](https://docs.apimart.ai/fr/api-reference/images/minimax-h3-image-highspeed/generation.md) | Par défaut, MiniMax H3 Image commence par enrichir automatiquement le prompt en une description détaillée de la scène, puis génère l’image. Le texte enrichi est disponible dans `revised_prompt` du résultat de la tâche. Pour générer strictement à partir du texte d’origine, voir [Désactiver la réécriture du prompt](#désactiver-la-réécriture-du-prompt). > [!WARNING] > > Sans `resolution`, la sortie est en **4K** par défaut (environ 16 mégapixels), pour un prix environ 3 fois supérieur à 1K / 2K. Si vous n’avez pas besoin de 4K, passez explicitement `"resolution": "2K"`. ## Paramètres de requête **model** `string` *required* Nom du modèle de génération d’images, toujours `minimax-h3-image`. **prompt** `string` *required* Description textuelle de l’image à générer ou à retoucher. Prend en charge le chinois et l’anglais. Longueur de `1` à `32,000` caractères après suppression des espaces de début et de fin. **image\_urls** `string[]` Tableau d’images de référence, `16` au maximum. Sa présence active automatiquement le mode retouche. Chaque élément peut être un lien direct `http(s)://` accessible publiquement ou du Base64 intégré au format `data:image/png;base64,...` (la plateforme le convertit d’abord en lien avant de le transmettre au modèle). Voir [Exigences pour les images de référence](#exigences-pour-les-images-de-référence). **size** `string` (default: auto) Format ou dimensions exactes en pixels de l’image de sortie. Valeurs prises en charge : * `auto` : le modèle choisit la composition et le format selon le prompt * Format : `X:Y`, avec X et Y entiers de `1` à `300` et un rapport compris entre `1:3` et `3:1` (bornes incluses), par exemple `1:1`, `4:3`, `16:9`, `9:16`, `3:1` * Pixels exacts : `largeurxhauteur`, par exemple `2048x1152` (les séparateurs `X`, `×` et `*` sont aussi acceptés) Voir [Règles de dimensions](#règles-de-dimensions). **resolution** `string` (default: 4K) Niveau de résolution ; combiné au format, il détermine le nombre réel de pixels en sortie. * `1K` : environ 1 mégapixel * `2K` : environ 4,2 mégapixels * `4K` (par défaut) : environ 16 mégapixels Les minuscules sont acceptées. > [!WARNING] > > Lorsque `size` est en pixels exacts, `resolution` **ne doit pas** être passé, sinon une erreur 400 est renvoyée. **n** `integer` (default: 1) Nombre d’images à générer, de `1` à `10`. **prompt\_optimizer** `boolean` (default: true) Active ou non l’enrichissement automatique du prompt. `false` ne s’applique qu’au texte vers image et exige des dimensions explicites ; voir [Désactiver la réécriture du prompt](#désactiver-la-réécriture-du-prompt). **output\_format** `string` (default: jpeg) Format du fichier de sortie. * `jpeg` (par défaut, `jpg` est aussi accepté) * `png` * `webp` **output\_compression** `integer` (default: 95) Qualité de compression de `0` à `100` ; sans effet sur `png`. **watermark** `boolean` (default: false) Ajoute ou non un filigrane visible indiquant une génération par IA. N’affecte pas le marquage invisible dans les métadonnées de l’image. > [!NOTE] > > Les paramètres suivants ne sont pas pris en charge et sont ignorés : `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`. > > Les résultats sont toujours renvoyés sous forme d’URL ; passer `response_format: "b64_json"` renvoie une erreur 400. ## Règles de dimensions | Objectif | Paramètres à passer | | - | - | | Par défaut (4K, format choisi par le modèle) | Aucun paramètre de dimensions | | Niveau + format | `size: "16:9"`, `resolution: "2K"` | | Niveau seul, format choisi par le modèle | `resolution: "1K"` (`size` omis ou `auto`) | | Contrôle au pixel près | `size: "2048x1152"` (**ne pas passer `resolution`**) | ### Niveau + format Le niveau détermine la surface totale, le format détermine la forme : | Niveau | Surface cible | Exemple de sortie mesuré | | - | - | - | | `1K` | environ 1024×1024 (environ 1 mégapixel) | format choisi par le modèle → 1184×880 | | `2K` | environ 2048×2048 (environ 4,2 mégapixels) | `1:1` → 2048×2048 | | `4K` (par défaut) | environ 4096×4096 (environ 16 mégapixels) | format choisi par le modèle → 3552×4736 | Le modèle arrondit le nombre réel de pixels selon le format et le niveau ; seul le résultat renvoyé fait foi. Pour des dimensions exactes, utilisez la notation en pixels. ### Pixels exacts Avec `size: "largeurxhauteur"`, les conditions suivantes s’appliquent : | Contrainte | Valeur | | - | - | | Nombre total de pixels (largeur × hauteur) | `655,360` \~ `20,000,000` | | Format | `1:3` \~ `3:1` | | Avec `resolution` | Ne pas passer les deux en même temps | * ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000` * ❌ `512x512` (surface trop petite), `4000x1000` (format au-delà de 3:1), `5000x5000` (plus de 20 mégapixels) ## Exigences pour les images de référence | Élément | Exigence | | - | - | | Nombre | 16 au maximum | | Format | JPG / JPEG / PNG / WebP / HEIC / HEIF (GIF non pris en charge) | | Taille du fichier | 64 Mo maximum par image | | Dimensions | Chaque côté de 128 \~ 8192 pixels, côté long ÷ côté court ≤ 4 | > [!WARNING] > > Avec des URL, assurez-vous que le lien est **accessible publiquement**. Si le lien est inaccessible, la tâche échoue pendant la génération (`status` vaut `failed`, le montant est intégralement remboursé). > > En mode retouche, l’optimisation du prompt est toujours active et ne peut pas être désactivée. ## Désactiver la réécriture du prompt Par défaut, le modèle enrichit d’abord le prompt, puis génère l’image. Pour générer strictement à partir du texte d’origine, passez `"prompt_optimizer": false`, à condition que : * La requête soit en **texte vers image** uniquement ; avec `image_urls`, une erreur 400 est renvoyée * Les dimensions soient **explicites** : `size` doit être un format (par exemple `1:1`) ou des pixels (par exemple `1024x1024`), ni `auto` ni omis Une fois l’optimisation désactivée, le modèle ne lit qu’environ les 4096 premiers tokens du prompt. ## Response **code** `integer` Code de réponse ; 200 lorsque l’envoi réussit. **data** `array` Données de la réponse d’envoi. **Élément du tableau** **status** `string` État initial : `submitted`. **task\_id** `string` Identifiant unique utilisé pour consulter l’état et le résultat. ## Réponse d’envoi Une fois l’envoi réussi, l’ID de la tâche asynchrone est renvoyé immédiatement : ```json theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01KXXXXXXXXXXXXXXX" } ] } ``` ## Consulter le résultat de la tâche Utilisez le `task_id` de la réponse d’envoi avec l’[endpoint de consultation 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/task_01KXXXXXXXXXXXXXXX \ --header 'Authorization: Bearer ' ``` En conditions réelles, une image 1K / 2K prend environ 10 \~ 20 secondes, une image 4K environ 20 secondes et une retouche avec références environ 20 secondes. Interrogez l’état toutes les 3 \~ 5 secondes jusqu’à obtenir `completed` ou `failed`. Une tâche peut durer jusqu’à 600 secondes ; fixez donc le délai d’attente du polling côté client à 10 minutes. ### Tâche réussie ```json theme={null} { "code": 200, "data": { "id": "task_01KXXXXXXXXXXXXXXX", "status": "completed", "progress": 100, "created": 1794450409, "completed": 1794450428, "actual_time": 19, "estimated_time": 60, "cost": 0.0493, "result": { "images": [ { "url": [ "https://upload.apimart.ai/f/image/example_0.jpeg", "https://upload.apimart.ai/f/image/example_1.jpeg" ], "expires_at": 1794536828, "revised_prompt": "The image is a realistic, close-up still life photograph of ...", "revised_prompts": [ "The image is a realistic ...", "The image is a professional ..." ] } ] } } } ``` Les URL des images se trouvent dans `data.result.images[0].url[]` ; les `n` images sont toutes dans ce même tableau. Téléchargez-les et conservez-les avant `expires_at`. En cas d’échec, `status` vaut `failed`, la cause figure dans `error.message` et le montant est automatiquement remboursé en totalité. ## Exemples d’utilisation ### Texte vers image (4K par défaut) ```json theme={null} { "model": "minimax-h3-image", "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones" } ``` ### Texte vers image (1K + format, 4 images) ```json theme={null} { "model": "minimax-h3-image", "prompt": "Visuel produit minimaliste d’un casque audio, fond blanc, ombres douces", "size": "1:1", "resolution": "1K", "n": 4 } ``` ### Pixels exacts + PNG ```json theme={null} { "model": "minimax-h3-image", "prompt": "Affiche d’une ville de nuit, néons, style cyberpunk, titre NIGHT CITY", "size": "2048x1152", "output_format": "png" } ``` ### Retouche avec images de référence ```json theme={null} { "model": "minimax-h3-image", "prompt": "Habille la personne de la première image avec la veste de la deuxième image, sans modifier l’arrière-plan", "image_urls": [ "https://example.com/person.jpg", "https://example.com/jacket.png" ], "resolution": "2K" } ``` ### Désactiver la réécriture du prompt ```json theme={null} { "model": "minimax-h3-image", "prompt": "a red apple on a wooden table, top view", "size": "1:1", "resolution": "1K", "prompt_optimizer": false } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.