> ## Documentation Index > Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt > Use this file to discover all available pages before exploring further. # Génération d’images GPT-Image-2.5 > - Choisissez entre gpt-image-2.5-flare et gpt-image-2.5-sunburst - Traitement asynchrone avec un task_id pour consulter le résultat - Texte vers image et retouche avec jusqu’à 16 images de référence - Retouche locale avec un masque PNG transparent - 15 formats, dimensions exactes et résolutions 1K / 2K / 4K - Qualités low / medium / high / xhigh / max > [!NOTE] > > **Choix du modèle :** `gpt-image-2.5-flare` est plus rapide et convient aux créations courantes, aux lots et au prototypage. `gpt-image-2.5-sunburst` privilégie la précision de retouche pour les visuels finalisés, les créations publicitaires et les modifications détaillées en plusieurs étapes. Les deux modèles ont la même tarification. ```bash cURL theme={null} curl --request POST \ --url https://gccai.heqingsong.uk/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "gpt-image-2.5-flare", "prompt": "un coin lecture chaleureux près d’une fenêtre sous la pluie, lumière douce", "size": "1:1", "resolution": "1k", "quality": "medium", "n": 1 }' ``` ```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" } } ``` ## Authentification **Authorization** `string` *required* Tous les endpoints utilisent un Bearer Token. Obtenez votre clé sur la [page des clés API](https://gccai.heqingsong.uk/keys). ``` Authorization: Bearer YOUR_API_KEY ``` ## Choisir un modèle | Modèle | Point fort | Utilisation recommandée | | - | - | - | | `gpt-image-2.5-flare` | Modèle par défaut, plus rapide | Réseaux sociaux, produits, recherche visuelle, prototypes et génération en lot | | `gpt-image-2.5-sunburst` | Précision de retouche | Visuels finalisés, publicité et retouche détaillée en plusieurs étapes | À paramètres identiques, les deux modèles consomment le même nombre de tokens et coûtent le même prix. GPT-Image-2.5 ajoute `xhigh` et `max` par rapport à `gpt-image-2` ; ses niveaux `medium` et `high` utilisent environ quatre fois moins de tokens de sortie que les niveaux homonymes de la génération précédente. ## Paramètres de requête **model** `string` *required* Modèle : `gpt-image-2.5-flare` ou `gpt-image-2.5-sunburst`. **prompt** `string` *required* Description de l’image à créer ou modifier. Précisez le sujet, la scène, la composition, le style, la lumière et les éléments à conserver ou changer. **size** `string` (default: auto) Format de sortie ou dimensions exactes. * `auto` : choix automatique d’après le prompt ou les références * Format : `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3` * Dimensions exactes, par exemple `1600x1200` > [!TIP] > > Pour une retouche, omettez `size` afin que le service calcule les dimensions à partir de l’image source et de `resolution`. **resolution** `string` (default: 1k) Niveau de résolution : `1k`, `2k` ou `4k`. Ignoré lorsque `size` contient des dimensions exactes. **quality** `string` (default: auto) Qualité : `low`, `medium`, `high`, `xhigh`, `max` ou `auto`. > [!WARNING] > > `xhigh` et `max` sont réservés à GPT-Image-2.5. Les envoyer à `gpt-image-2` renvoie HTTP 400 sans réduction automatique. **n** `integer` (default: 1) Nombre d’images : de `1` à `4`. Envoyez un nombre, pas une chaîne. **output\_format** `string` (default: png) Format : `png`, `jpeg` ou `webp`. **output\_compression** `integer` Compression de `0` à `100`, uniquement pour `jpeg` et `webp`. **background** `string` Arrière-plan : `transparent`, `opaque` ou `auto`. > [!WARNING] > > `transparent` exige `png` ou `webp`, car JPEG ne possède pas de canal alpha. **moderation** `string` (default: low) Niveau de modération : `auto` ou `low`. GccAi envoie explicitement `low` si le champ est absent ; une valeur `auto` explicite est conservée. **image\_urls** `string[]` Images de référence pour la génération ou la retouche, au maximum `16`. La présence de ce champ active le mode édition. Seules les URL HTTP(S) publiques sont acceptées. Pour une image locale, utilisez d’abord `POST /v1/uploads/images`, puis la valeur `url` renvoyée. **mask\_url** `string` Masque destiné à la retouche locale. Il ne prend effet que si `image_urls` est également fourni. `gpt-image-2.5-flare` et `gpt-image-2.5-sunburst` prennent tous deux ce paramètre en charge. Fournissez une seule chaîne dans l’un des formats suivants : * Une URL HTTP(S) d’image que le serveur peut télécharger directement * Une Data URL PNG au format `data:image/png;base64,...` Exigences du masque : * Utiliser un PNG doté d’un canal alpha transparent ; PNG est aussi recommandé pour l’image source * Ses dimensions en pixels doivent correspondre exactement à `image_urls[0]`. Elles doivent correspondre à la première image d’entrée, et non au `size` de sortie * Les pixels entièrement transparents (`alpha=0`) définissent la zone à modifier ; les autres zones servent à la conservation * Envoyer un seul masque par requête. Avec plusieurs images de référence, il ne s’applique qu’à la première image d’entrée * Le guide général indique moins de `50 MB`, tandis que la documentation du paramètre `mask` indique moins de `4 MB`. Jusqu’à vérification, utilisez la limite plus stricte de `4 MB` > [!WARNING] > > Une simple image en noir et blanc dépourvue de canal alpha ne peut pas servir directement de masque. GccAi n’ajoute pas de canal alpha et ne vérifie actuellement pas au préalable que les dimensions du masque correspondent à l’image source ; le client doit garantir ces deux points. > [!NOTE] > > Une URL HTTP(S) doit être accessible sans Cookie ni en-tête d’autorisation supplémentaire. Une URL signée doit rester valide pendant la mise en file d’attente et l’exécution. Par défaut, le téléchargement est limité à `20 MB` avec un délai d’expiration de `60` secondes ; le déploiement peut remplacer ces valeurs. > > Le masque guide la retouche, mais le modèle ne garantit pas que les pixels situés hors de ses limites restent parfaitement inchangés. ## Règles de dimensions * Largeur et hauteur doivent être des multiples de `16` * Aucun côté ne doit dépasser `3840` pixels * Le rapport côté long / côté court ne doit pas dépasser `3:1` * Le nombre total de pixels doit être compris entre `655 360` et `8 294 400` > [!WARNING] > > Les résolutions supérieures à 2560×1440 sont expérimentales et peuvent être moins stables. ### Correspondance format et résolution | `size` | `1k` | `2k` | `4k` | | - | - | - | - | | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `3:2` | 1536×1024 | 2048×1360 | 3520×2336 | | `2:3` | 1024×1536 | 1360×2048 | 2336×3520 | | `4:3` | 1024×768 | 2048×1536 | 3312×2480 | | `3:4` | 768×1024 | 1536×2048 | 2480×3312 | | `5:4` | 1280×1024 | 2560×2048 | 3216×2576 | | `4:5` | 1024×1280 | 2048×2560 | 2576×3216 | | `16:9` | 1536×864 | 2048×1152 | 3840×2160 | | `9:16` | 864×1536 | 1152×2048 | 2160×3840 | | `2:1` | 2048×1024 | 2688×1344 | 3840×1920 | | `1:2` | 1024×2048 | 1344×2688 | 1920×3840 | | `21:9` | 2016×864 | 2688×1152 | 3840×1648 | | `9:21` | 864×2016 | 1152×2688 | 1648×3840 | | `3:1` | 1536×512 | 3072×1024 | 3840×1280 | | `1:3` | 512×1536 | 1024×3072 | 1280×3840 | Vous pouvez également fournir d’autres dimensions exactes si elles respectent toutes les règles. ## Exemple de retouche ```json theme={null} { "model": "gpt-image-2.5-sunburst", "prompt": "conserver le produit et le texte de l’emballage, remplacer le fond par un studio blanc cassé et ajouter une ombre naturelle", "image_urls": ["https://example.com/product.png"], "resolution": "2k", "quality": "xhigh" } ``` ### Retouche locale avec un masque Cet exemple ne modifie que la zone entièrement transparente du masque. Ses dimensions doivent correspondre à `product.png`. ```json theme={null} { "model": "gpt-image-2.5-sunburst", "prompt": "remplacer uniquement la zone couverte par le masque transparent par un ruban doré, tout en conservant le produit et le reste de l’arrière-plan", "image_urls": [ "https://example.com/product.png" ], "mask_url": "https://example.com/product-mask.png", "quality": "xhigh" } ``` ## Envoi et consultation de la tâche Après un envoi réussi, l’ID de tâche se trouve dans `data[0].task_id`. Interrogez le [statut de la tâche](https://gccai.heqingsong.uk/fr/api-reference/tasks/status.md) toutes les 2 à 5 secondes jusqu’à `completed` ou `failed`. Utilisez `POST /v1/tasks/batch` pour plusieurs tâches. ```json theme={null} { "code": 200, "data": { "id": "task_01KXXXXXXXXXXXXXXX", "status": "completed", "progress": 100, "cost": 0.01325, "result": { "images": [ { "url": ["https://upload.gccai.ai/f/image/example.png"], "expires_at": 1789000000 } ] }, "usage": { "input_tokens": 16, "output_tokens": 439, "total_tokens": 455 } } } ``` Les images sont dans `data.result.images[].url[]`. Téléchargez-les et stockez-les rapidement. | Statut | Signification | | - | - | | `submitted` | Tâche envoyée | | `processing` | Génération en cours | | `completed` | Réussite ; `result.images` est disponible | | `failed` | Échec ; consultez `error.message` ; la somme réservée est remboursée | ## Facturation GPT-Image-2.5 est facturé selon les tokens réellement consommés. Consultez la [page des tarifs](https://gccai.heqingsong.uk/pricing) ou `/api/pricing` pour le tarif de votre compte. | Élément | Prix par million de tokens | | - | - | | Sortie image | \$30.00 | | Entrée image | \$8.00 | | Entrée image en cache | \$2.00 | | Entrée texte | \$5.00 | | Entrée texte en cache | \$1.25 | | `quality` à 1024×1024 | Tokens de sortie | Coût officiel de sortie | | - | - | - | | `low` | 196 | \$0.00588 | | `medium` | 439 | \$0.01317 | | `high` | 1756 | \$0.05268 | | `xhigh` | 3122 | \$0.09366 | | `max` | 7024 | \$0.21072 | > [!WARNING] > > Avec `quality: "auto"`, le service réserve d’abord le montant du niveau `max` pour la taille choisie. À la fin, il facture l’usage réel et libère la différence. Pour `n > 1`, la réservation augmente linéairement. Les tâches échouées sont remboursées automatiquement. ## Limites et erreurs fréquentes | Élément | Limite ou solution | | - | - | | Images par requête | 1–4 | | Images de référence | 16 au maximum | | Format de sortie | PNG / JPEG / WebP | | Fond transparent | PNG / WebP uniquement | | Images partielles en streaming | Non pris en charge | | Qualité non valide | `xhigh` / `max` exigent GPT-Image-2.5 | | Dimensions non valides | Utilisez des multiples de 16 dans les limites de pixels et de format | ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.