Guide de l'API GPT Image 2.5 : Génération et édition d'images avec Sunburst et Flare

Utilisez Image API pour la génération et l'édition directes en une seule étape. Lorsque la création d'images fait partie d'un processus de dialogue ou en plusieurs étapes, utilisez Responses API. Dans l'Image API, sélectionnez directement gpt-image-2.5-sunburst ou gpt-image-2.5-flare.

Choisissez d'abord l'interface

L'API d'images fournit des points de terminaison pour la génération et l'édition. L'API de réponse prend en charge la génération itérative d'images en tant qu'outil et peut conserver les entrées et sorties d'images dans le contexte. Cette décision architecturale est plus importante que la syntaxe du SDK.

Mode de génération minimal

// 这是一个示例函数，用于演示翻译功能
function greet(name) {
    return "你好，" + name + "！";
}

import OpenAI from "openai"; import fs from "fs";

const client = new OpenAI(); const result = await client.images.generate({ model: "gpt-image-2.5-flare", prompt: "une illustration de design épuré représentant une bibliothèque solaire, sans élément textuel" size: "1536x1024", quality: "Moyenne", output_format: "png" });

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

Conservez la clé API côté serveur et éloignez-la du contrôle de code source.

## Contrôle de sortie

Les deux modèles prennent en charge, de l’automatique à la qualité maximale, des dimensions personnalisées dans les limites officielles, les formats PNG/JPEG/WebP, la compression JPEG/WebP, ainsi que des arrière-plans transparents ou opaques. Pour un canal alpha, veuillez utiliser les formats PNG ou WebP.

## Mode d'édition

Utilisez une ou plusieurs images pour appeler le point de terminaison d'édition, et fournissez une invite qui sépare les modifications des détails à conserver. Vérifiez le type et la taille des entrées avant l'envoi. Attribuez un rôle à chaque référence.

## Validation de la production

Stockez l'ID de la requête, le modèle ou l'instantané, la version de l'invite, la taille, la qualité, le format de sortie, les informations de référence, la latence et le résultat accepté. Ne réessayez que les pannes transitoires ; sans modifier la requête, ne réessayez pas automatiquement les sorties avec des erreurs sémantiques.

## Routage des modèles

Acheminez les tâches quotidiennes vers Flare et les tâches de haute précision vers Sunburst. Utilisez des références fixes, évitez de supposer que les modèles plus rapides sont moins chers, car les tarifs actuels des jetons correspondent.

## Gestion des erreurs

Traiter l'authentification, la vérification d'organisation, la limitation de débit, les dimensions invalides, la modération de contenu et les sorties vides. Pour les erreurs transitoires éligibles, utiliser une stratégie de backoff exponentiel avec gigue et limiter le nombre de tentatives. Ne jamais enregistrer inutilement des données d'images privées.

## Animation en aval

Après avoir décodé et approuvé l'image, stockez les informations sources et transmettez l'actif aux workflows en aval. Lorsqu'une image statique doit devenir un storyboard, une vidéo ou une animation éditoriale axée sur les personnages, [Elser AI](https://www.elser.ai/fr) est pertinent. Veuillez vérifier les options de téléchargement et de modèle prises en charge dans le produit en temps réel.

## Point de terminaison de génération et point de terminaison d'édition

Utilisez la fonction de génération pour créer de nouvelles images à partir de texte. Utilisez la fonction d'édition lorsqu'une ou plusieurs images existantes définissent le sujet ou l'état initial. Pour les modifications multi-références, envoyez les entrées dans un ordre stable et identifiez cet ordre dans l'invite. Avant la requête, vérifiez le type et les dimensions des fichiers afin que les entrées erronées échouent localement.

## API de réponse pour le travail itératif

L'API Responses est très utile lorsque les utilisateurs créent des images, les évaluent de manière conversationnelle et demandent des modifications ultérieures. L'outil de génération d'images peut participer à un flux de réponse plus large, et l'ID du fichier image peut être conservé dans le contexte. Cela réduit le travail d'assemblage côté application, mais le produit nécessite toujours un contrôle d'état et de version explicite. « Comme avant » n'est pas suffisant comme contrainte clé ; veuillez reformuler.

## Architecture d'application plus sécurisée

Garder le client, la file d'attente des tâches, le stockage des actifs et le stockage des métadonnées indépendants les uns des autres. Le client soumet une brève description. Le serveur valide cette description et crée une tâche. Le processus de travail appelle OpenAI, décode le résultat et le stocke sous l'ID d'actif généré. Les métadonnées enregistrent l'instantané du modèle, les invites, les paramètres, les références et les résultats de validation. Le client reçoit une URL d'actif à courte durée de validité, et non les informations d'identification originales.

Les appels de longue durée ne doivent pas monopoliser les requêtes fragiles du navigateur. Les invites complexes peuvent nécessiter beaucoup de temps, il convient donc d'afficher les statuts en attente, terminés et échoués. Rendre la soumission des tâches idempotente afin d'éviter des frais en double lors des tentatives de reprise côté client.

## Règles de validation

Vérifiez si les dimensions personnalisées respectent les multiples de 16, les marges, les proportions et les limites de pixels totaux définis dans la documentation. Lorsque l'arrière-plan est transparent, utilisez les formats PNG ou WebP. Limitez la valeur de compression à la plage prise en charge. Seuls les paramètres de qualité et de modèle connus sont autorisés. Avant d'appeler l'API, rejetez les cas où les invites sont manquantes.

## Fiabilité et Observabilité

Enregistrez l'ID de la requête, le statut HTTP, la catégorie d'erreur, le nombre de tentatives et la latence, sans enregistrer les images privées ou les informations confidentielles. Utilisez un backoff exponentiel avec gigue pour les limites de taux de retry et les erreurs de serveur éligibles. Ne réessayez pas les erreurs d'authentification, les paramètres invalides ou les erreurs de politique. Fixez une limite au nombre de tentatives et renvoyez un message produit utile.

Écran :

- Taux de réussite et taux d'acceptation des images.
- Latence p50 et p95 par modèle et qualité.
- Jetons d'entrée et de sortie.
- Tâches de réessai et de répétition.
- Résultat de l'examen.
- Échec du stockage et de la livraison.

## Sécurité et droits

Stockez la clé API dans un gestionnaire de clés côté serveur. Appliquez des contrôles d'accès aux images sources et générées. Établissez des règles de conservation, supprimez les métadonnées qui ne devraient pas être exposées et enregistrez les droits des utilisateurs sur les éléments téléchargés. OpenAI indique que l'accès au modèle d'images GPT peut nécessiter une vérification organisationnelle ; traitez-la comme une condition préalable à l'intégration plutôt qu'une surprise lors de l'exécution.

## Stratégie de snapshots

Utilisez des identifiants non datés pour obtenir des mises à jour continues du modèle. Lorsque la reproductibilité est plus importante, fixez un instantané daté. Avant de modifier le trafic de production, évaluez le nouvel instantané à l'aide du même référentiel. Stockez l'identifiant réel du modèle renvoyé ou configuré pour chaque actif.

Si l'article de démarrage contient du code, veuillez afficher à côté la date de validation avec la date. Les lecteurs doivent comprendre que la disponibilité du modèle, la syntaxe du SDK, les limites de taux et les exigences organisationnelles peuvent changer indépendamment de l'architecture conceptuelle de l'article.

## Contrat de requête typé

Même si le modèle d'image lui-même ne fournit pas de sortie structurée, définissez un schéma interne. Une tâche peut inclure `prompt` (invite), `workflow` (flux de travail), `model` (modèle), `quality` (qualité), `width` (largeur), `height` (hauteur), `format` (format), `background` (arrière-plan), `compression` (compression), un ID de ressource de référence et une clé idempotente. Validez-la avant de la convertir en appel SDK.

N'exposez pas de noms de modèles ou de chemins de fichiers arbitraires depuis le navigateur. Mappez plutôt les quelques options visibles côté client vers des valeurs approuvées par le serveur. Résolvez les références via des identifiants d'actifs contrôlés par accès, et vérifiez que l'utilisateur actuel est autorisé à lire ces actifs.

## Ébauche de demande d'édition

```javascript
{
  "headers": {
    "rows": "Lignes",
    "videourl": "URL de la vidéo"
  }
}

import OpenAI from "openai"; import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({ model: "gpt-image-2.5-sunburst", image: [fs.createReadStream("approved-character.png")], prompt : `Modifiez uniquement le manteau en laine vert foncé. Conserver le visage, la couleur des cheveux, la couleur des yeux, la posture, les mains, la composition et l'arrière-plan. Ne pas ajouter de texte, de bijoux ou d'autres personnes. size: "1024x1536", quality: "haute", output_format: "png" });

const bytes = Buffer.from(result.data[0].b64_json, "base64"); fs.writeFileSync("character-green-coat.png", bytes);

Les interfaces SDK exactes peuvent évoluer, veuillez donc vérifier les exemples par rapport au guide officiel actuel avant le déploiement. Le code de production doit gérer le streaming ou la mise en mémoire tampon de manière responsable, vérifier l'existence des réponses et les stocker de manière atomique, sans supposer que chaque appel renvoie des données utilisables.

## Idempotence et coût de répétition

Un double clic de l'utilisateur ou une tentative réseau peut entraîner la soumission deux fois d'une même tâche de génération coûteuse. Attribuez une clé idempotente lors de la création de la tâche, persistez-la avant la distribution, et renvoyez la tâche existante lorsque la même clé réapparaît. Le processus de travail ne doit récupérer la tâche qu'une seule fois et enregistrer l'état final.

Si vous souhaitez générer plusieurs variantes, veuillez le représenter comme une opération produit explicite, et non comme une tentative accidentelle. L'API d'images prend en charge la génération de plusieurs images via le paramètre `n` dans la documentation, mais votre modèle de coûts et de vérification doit comptabiliser chaque sortie.

## Expérience utilisateur en matière de révision et d'échec

Tous les prompts et images doivent passer par un filtre de sécurité. Évitez de divulguer des détails sensibles sur la modération interne, mais donnez aux utilisateurs suffisamment de conseils pour modifier les demandes légitimes. Distinguez les refus liés aux politiques des paramètres invalides, des autorisations, des limites de débit et des pannes temporaires de service.

Lorsque Sunburst n'est pas disponible, ne le remplacez jamais silencieusement par un autre modèle, car cela pourrait violer les engagements de qualité ou contractuels. Vous devez renvoyer un état explicite, ou n'utiliser une solution de repli que si le produit a déjà divulgué et documenté ce comportement.

## Stockage et livraison des actifs

Décoder le base64 en mémoire et définir une limite de taille, valider le format déclaré, générer une somme de contrôle et stocker le fichier brut immuable. Générer les vignettes séparément. Servir via des URL signées à courte durée de validité et avec le type de contenu approprié. Conserver le canal alpha des PNG/WebP transparents, éviter les conversions avec perte qui endommageraient les livrables.

Stockez les astuces et documents de référence avec des contrôles d'accès appropriés, en fonction de leur niveau de sensibilité. Définissez les comportements de conservation et de suppression. Les fichiers générés sans source sont difficiles à auditer, à reproduire ou à transmettre en toute sécurité au projet d'animation Elser.

## Liste de vérification avant publication

- Accès au compte et à l'organisation confirmé.
- La clé API est côté serveur et peut être renouvelée.
- L'ID du modèle et les règles de dimension sont sur la liste blanche.
- La soumission des devoirs est idempotente.
- Nombre de tentatives limité et classification.
- Les conditions d'utilisation, la latence et le taux d'acceptation sont surveillés.
- Les images et les métadonnées ont des règles de conservation.
- Pour les sorties sensibles à l'identité, à la marque et au texte, une vérification humaine est effectuée.
- Une stratégie de snapshot datée et un chemin de restauration ont été enregistrés.

## Foire aux questions

### Quelle API devrais-je choisir ?
L'API Image est utilisée pour la génération/édition directe ; l'API Responses est utilisée pour les expériences d'image conversationnelles ou multi-étapes.

### Puis-je demander plusieurs images ?
L'API Image prend en charge le paramètre `n` pour plusieurs sorties dans la documentation.

### L'API renvoie-t-elle une URL ?
Ce guide actuel montre les données d'image encodées en base64 de l'API d'images ; veuillez les décoder et les stocker en toute sécurité.

## Conclusion

Une intégration fiable allie un routage clair des modèles à une validation rigoureuse, une observabilité et une vérification des actifs. Construisez d’abord la requête directe minimale, puis ajoutez l’état conversationnel ou les animations en aval uniquement lorsque le chemin d’image principal est fiable.