Génération d’images GPT-Image-2.5

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Paramètres de requête invalides",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Échec de l’authentification. Vérifiez votre clé API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Solde du compte insuffisant",
    "type": "payment_required"
  }
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Paramètres de requête invalides",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Échec de l’authentification. Vérifiez votre clé API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Solde du compte insuffisant",
    "type": "payment_required"
  }
}

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.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Paramètres de requête invalides",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Échec de l’authentification. Vérifiez votre clé API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Solde du compte insuffisant",
    "type": "payment_required"
  }
}

Authentification

string

requis

Tous les endpoints utilisent un Bearer Token. Obtenez votre clé sur la page des clés API.

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

string

requis

Modèle : gpt-image-2.5-flare ou gpt-image-2.5-sunburst.

string

requis

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.

string

défaut:"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

Pour une retouche, omettez size afin que le service calcule les dimensions à partir de l’image source et de resolution.

string

défaut:"1k"

Niveau de résolution : 1k, 2k ou 4k. Ignoré lorsque size contient des dimensions exactes.

string

défaut:"auto"

Qualité : low, medium, high, xhigh, max ou auto.

xhigh et max sont réservés à GPT-Image-2.5. Les envoyer à gpt-image-2 renvoie HTTP 400 sans réduction automatique.

integer

défaut:"1"

Nombre d’images : de 1 à 4. Envoyez un nombre, pas une chaîne.

string

défaut:"png"

Format : png, jpeg ou webp.

integer

Compression de 0 à 100, uniquement pour jpeg et webp.

string

Arrière-plan : transparent, opaque ou auto.

transparent exige png ou webp, car JPEG ne possède pas de canal alpha.

string

défaut:"low"

Niveau de modération : auto ou low. APIMart envoie explicitement low si le champ est absent ; une valeur auto explicite est conservée.

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.

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

Une simple image en noir et blanc dépourvue de canal alpha ne peut pas servir directement de masque. APIMart 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.

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

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

{
  "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.

{
  "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 toutes les 2 à 5 secondes jusqu’à completed ou failed. Utilisez POST /v1/tasks/batch pour plusieurs tâches.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [
        {
          "url": ["https://upload.apimart.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 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

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

integer

Code de réponse ; 200 lorsque l’envoi réussit.

array

Données de la réponse d’envoi.

Afficher Élément du tableau

string

État initial : submitted.

string

Identifiant unique utilisé pour consulter l’état et le résultat.

Aperçu

Modèles

Série Texte

Série Image

Série Vidéo

Série Audio

Série Modération

Gestion des uploads

Gestion des tâches

Gestion du compte

Génération d’images GPT-Image-2.5

Authentification

Choisir un modèle

Paramètres de requête

Règles de dimensions

Correspondance format et résolution

Exemple de retouche

Retouche locale avec un masque

Envoi et consultation de la tâche

Facturation

Limites et erreurs fréquentes

Response

​Authentification

​Choisir un modèle

​Paramètres de requête

​Règles de dimensions

​Correspondance format et résolution

​Exemple de retouche

​Retouche locale avec un masque

​Envoi et consultation de la tâche

​Facturation

​Limites et erreurs fréquentes

​Response

Authentification

Choisir un modèle

Paramètres de requête

Règles de dimensions

Correspondance format et résolution

Exemple de retouche

Retouche locale avec un masque

Envoi et consultation de la tâche

Facturation

Limites et erreurs fréquentes

Response