Migrer une intégration d’images vers SeedRouter

Migrer une API d’images vers SeedRouter suppose de vérifier le contrat de requête et de réponse, pas seulement de remplacer la clé d’API et l’URL de base. GPT Image 2 utilise des champs de génération d’images familiers, mais l’envoi renvoie un identifiant de tâche. Votre application doit enregistrer cet identifiant, interroger la tâche jusqu’à son achèvement, puis lire les URL des images finales.

La plus petite migration utile est une requête texte-vers-image depuis du code côté serveur. Faites-la fonctionner avant de déplacer les retouches avec référence, les masques ou un lot plus important. Gardez l’intégration existante disponible tant que le nouveau chemin n’a pas passé les mêmes contrôles de recette.

Quelles hypothèses doivent changer ?

Repérez le code qui transforme une requête d’image en fichier utilisable. Il attend peut-être aujourd’hui une image dans la première réponse, décode un champ base64 ou utilise un envoi multipart. Ces hypothèses doivent être vérifiées une à une face à la référence SeedRouter de GPT Image 2.

C’est pourquoi un appel synchrone d’un SDK Images n’est pas un remplacement direct, même s’il accepte une URL de base configurable. Conservez les réglages de modèle dont vous avez encore besoin, mais adaptez le code applicatif qui attend et exploite le résultat.

Faites correspondre les champs avant de déplacer du code

Commencez par model, prompt, size, quality et n. Utilisez gpt-image-2 comme identifiant de modèle. Envoyez des dimensions explicites comme 1024x1024 ou utilisez auto ; ne reportez pas un champ resolution distinct ni une chaîne de ratio comme taille.

Le document OpenAPI de SeedRouter est un bon compagnon de relecture. Comparez les champs que votre application envoie réellement, y compris les valeurs ajoutées par un SDK, plutôt que de vérifier seulement les arguments visibles à l’appel. Les champs inconnus sont rejetés.

Pour ce modèle, style, response_format et un input_fidelity configurable ne sont pas des champs de requête acceptés. Supprimez ces hypothèses plutôt que de les dissimuler dans un objet d’options générique. La requête ne prend pas non plus en charge stream ni partial_images ; dans cette intégration, c’est l’état de la tâche qui rend compte de la progression.

Les réglages de sortie ont des dépendances. Si vous demandez la transparence, choisissez PNG. N’envoyez output_compression que pour JPEG, pas pour PNG. Une valeur de compression nulle est valide : évitez donc un test de véracité qui la remplacerait par une valeur par défaut. Ce sont de petits détails qu’une requête de base réussie ne met pas à l’épreuve.

Remplacez l’hypothèse d’une réponse synchrone

L’exemple Node.js suivant envoie une requête et affiche son identifiant de tâche. Définissez SEEDROUTER_API_KEY sur le serveur ; ne placez jamais la clé dans du code navigateur ni dans une variable d’environnement publique.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

Afficher l’identifiant suffit pour un test manuel rapide. Dans une application, enregistrez-le avant de rendre la main à l’utilisateur. Votre enregistrement d’image peut alors rester en attente pendant que l’utilisateur navigue ailleurs, et une vérification ultérieure récupérera le résultat.

Utilisez GET https://api.seedrouter.ai/v1/tasks/{id} avec le même en-tête d’autorisation pour suivre la progression. Sur completed, lisez output.data[].url. Sur failed, traitez l’erreur documentée et affichez un état d’échec approprié. Pour un exemple exécutable qui conserve la progression, voyez envoi par lots et suivi.

N’attachez pas la clé d’API à la requête de téléchargement de l’image. L’autorisation appartient à l’appel de l’API de tâches, pas à une récupération distincte d’une URL d’actif renvoyée.

Passez les références et les masques en entrées URL

Un flux existant fondé sur des fichiers locaux demande une étape de préparation supplémentaire : rendre l’image de référence disponible à une URL HTTP(S) accessible que vous contrôlez. Transmettez-la sous la forme images: [{"image_url": "https://example.com/reference.png"}], en remplaçant cette adresse par la vôtre. N’envoyez ni chemin de fichier, ni URL blob:, ni data URL base64, ni identifiant Files.

Vérifiez que l’URL fonctionne sans les cookies de connexion de votre navigateur. Une URL qui ne s’ouvre que dans votre session authentifiée n’est pas une référence utilisable pour cette requête. Gardez l’image accessible pendant le traitement de la tâche ; ne révoquez pas l’accès juste après l’envoi.

Un masque s’indique par mask: {"image_url": "https://example.com/mask.png"} et exige des images de référence. Il doit correspondre aux dimensions de la première image de référence. Passez en revue toutes les contraintes d’entrée média avant de déplacer un flux de retouche existant, en particulier les formats et les tailles de fichier.

Que doit couvrir la recette de migration ?

Testez le comportement dont dépend votre application, y compris l’interruption. Une image réussie prouve seulement qu’une requête a fonctionné. Elle ne prouve pas que votre état d’attente survit à un rechargement, ni qu’un échec de téléchargement évitera une génération en double.

• Envoyer une requête purement textuelle et enregistrer l’identifiant renvoyé avant le suivi.
• Arrêter le suivi, le relancer avec le même identifiant et vérifier qu’aucun POST supplémentaire n’a lieu.
• Traiter processing, completed et failed comme des états distincts.
• Télécharger une image terminée sans envoyer l’en-tête d’autorisation de l’API.
• Vérifier une retouche avec une URL accessible, puis la gestion d’échec avec une URL inaccessible.
• Valider les champs facultatifs, y compris une compression à zéro, à l’aide du schéma publié.
• Confirmer que les montants du compte sont lus dans l’historique d’utilisation, et non dans un champ de coût inventé de la réponse de tâche.

Utilisez des réponses simulées pour des tests d’échec et de délai reproductibles. Ne faites un petit test réel, délibéré, qu’une fois ces contrôles passés ; les générations réelles consomment du solde. Si le résultat de l’envoi est incertain, enquêtez avant de réessayer. Une exception locale ne prouve pas qu’aucune tâche n’a été acceptée.

Questions fréquentes

Puis-je conserver mes prompts existants ?

Oui, comme point de départ, à condition qu’ils respectent les contraintes de requête. Gardez quelques prompts représentatifs pour comparer, mais n’attendez pas des images identiques de générations répétées.

Ai-je besoin d’une nouvelle bibliothèque client ?

Pas pour les exemples présentés ici. De simples requêtes HTTP suffisent. Quel que soit le client retenu, il doit gérer l’envoi de tâches et leur suivi, au lieu d’attendre immédiatement une image finie.

Où trouver le coût final ?

Dans l’historique d’utilisation du compte. Une tâche terminée peut inclure la consommation de jetons, mais sa réponse publique n’a pas de champ de coût. Le guide des tarifs traite des estimations.

Achevez la migration à la frontière de l’application

Une migration d’API d’images est achevée lorsque l’application gère tout le cycle de vie du résultat : tâche acceptée, état d’attente, sortie finale, téléchargement et échec. Gardez le premier changement réduit, testez les cas d’interruption, et ne déplacez les requêtes restantes qu’une fois leurs hypothèses d’entrée et de sortie vérifiées.