Spostare un’integrazione di immagini su SeedRouter

Migrare una API di immagini su SeedRouter richiede di verificare il contratto di richiesta e risposta, non solo di sostituire la chiave API e l’URL di base. GPT Image 2 usa i consueti campi di generazione immagini, ma l’invio restituisce un identificativo di attività. La tua applicazione deve salvare quell’identificativo, interrogare lo stato fino al completamento e leggere gli URL delle immagini finite.

La migrazione utile più piccola è una singola richiesta da testo a immagine dal codice lato server. Falla funzionare prima di spostare le modifiche con riferimento, le maschere o un batch più ampio. Tieni disponibile l’integrazione esistente finché il nuovo percorso non supera gli stessi controlli di accettazione.

Quali presupposti vanno cambiati?

Individua il codice che trasforma una richiesta di immagine in un file utilizzabile. Potrebbe aspettarsi un’immagine nella risposta iniziale, decodificare un campo base64 o usare un caricamento multipart. Questi presupposti vanno verificati uno per uno rispetto alla documentazione di GPT Image 2 su SeedRouter.

Per questo una chiamata sincrona di un SDK Images non è un sostituto immediato, anche se accetta un URL di base configurabile. Conserva le impostazioni del modello che ti servono ancora, ma adatta il codice applicativo che attende e consuma il risultato.

Mappa i campi della richiesta prima di spostare il codice

Comincia da model, prompt, size, quality e n. Usa gpt-image-2 come identificativo del modello. Invia dimensioni esplicite come 1024x1024 oppure usa auto; non trasferire un campo resolution separato né una stringa di rapporto d’aspetto come dimensione.

Il documento OpenAPI di SeedRouter è un utile supporto alla revisione. Confronta i campi che la tua applicazione invia davvero, compresi i valori forniti da un SDK, invece di controllare solo gli argomenti visibili nel punto di chiamata. I campi sconosciuti vengono rifiutati.

Per questo modello, style, response_format e un input_fidelity configurabile non sono campi di richiesta accettati. Elimina questi presupposti invece di nasconderli dentro un oggetto di opzioni generico. La richiesta non supporta nemmeno stream o partial_images; lo stato dell’attività è il modo in cui questa integrazione comunica l’avanzamento.

Le impostazioni di uscita hanno dipendenze. Se chiedi la trasparenza, scegli PNG. Invia output_compression solo per JPEG, non per PNG. Un valore di compressione pari a zero è valido, quindi evita un controllo di verità che lo sostituisca con un valore predefinito. Sono piccoli dettagli che una richiesta di base andata a buon fine non mette alla prova.

Sostituisci il presupposto della risposta sincrona

L’esempio Node.js seguente invia una richiesta e stampa il suo identificativo di attività. Imposta SEEDROUTER_API_KEY sul server; non mettere mai la chiave nel codice del browser o in una variabile d’ambiente pubblica.

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.

Stampare l’identificativo basta per una prova manuale. In un’applicazione, salvalo prima di restituire il controllo all’utente. Il record dell’immagine può così restare in attesa mentre l’utente naviga altrove, e un controllo successivo può recuperare il risultato.

Usa GET https://api.seedrouter.ai/v1/tasks/{id} con la stessa intestazione di autorizzazione per controllare l’avanzamento. Con completed, leggi output.data[].url. Con failed, gestisci l’errore documentato e mostra uno stato di errore adeguato. Per un esempio eseguibile che salva l’avanzamento, vedi invio in batch e polling.

Non allegare la chiave API alla richiesta di download dell’immagine. L’autorizzazione riguarda la chiamata all’API delle attività, non un recupero separato dell’URL di un asset restituito.

Passa a riferimenti e maschere come input URL

Un flusso di lavoro basato su file locali richiede un passaggio di preparazione in più: rendi l’immagine di riferimento disponibile a un URL HTTP(S) accessibile che controlli tu. Passala come images: [{"image_url": "https://example.com/reference.png"}], sostituendo quell’indirizzo con il tuo. Non inviare un percorso di file, un URL blob:, un data URL base64 o un Files ID.

Verifica che l’URL funzioni senza i cookie di accesso del tuo browser. Un URL che si apre solo nella tua sessione autenticata non è un riferimento utilizzabile per questa richiesta. Mantieni l’immagine accessibile mentre l’attività è in elaborazione; non revocare l’accesso subito dopo l’invio.

Una maschera usa mask: {"image_url": "https://example.com/mask.png"} e richiede immagini di riferimento. Deve corrispondere alle dimensioni della prima immagine di riferimento. Rivedi tutti i vincoli sugli input multimediali prima di spostare un flusso di modifica esistente, in particolare formati e dimensioni dei file.

Cosa deve coprire il collaudo della migrazione?

Prova il comportamento su cui la tua applicazione fa affidamento, interruzioni comprese. Un’immagine riuscita dimostra solo che quella richiesta ha funzionato. Non dimostra che lo stato di attesa sopravviva a un ricaricamento né che un download fallito eviti una generazione duplicata.

• Invia una richiesta di solo testo e salva l’identificativo restituito prima di fare polling.
• Interrompi il polling, riavvialo con lo stesso identificativo e verifica che non parta nessun altro POST.
• Gestisci processing, completed e failed come stati distinti.
• Scarica un’immagine completata senza inviare l’intestazione di autorizzazione dell’API.
• Prova una modifica con riferimento usando un URL accessibile, poi verifica la gestione dell’errore con uno non accessibile.
• Convalida i campi opzionali, compressione a zero inclusa, usando lo schema pubblicato.
• Conferma che gli addebiti si leggano dallo storico di utilizzo, non da un campo di costo inventato nella risposta dell’attività.

Usa risposte simulate per test ripetibili di errore e timeout. Fai una piccola prova dal vivo, deliberata, solo dopo che quei controlli sono passati; le generazioni reali consumano saldo. Se l’esito dell’invio è incerto, indaga prima di ritentare. Un’eccezione locale non è la prova che nessuna attività sia stata accettata.

Domande frequenti

Posso tenere i prompt che ho già?

Sì, come punto di partenza, purché rispettino i vincoli della richiesta. Conserva qualche prompt rappresentativo per il confronto, ma non aspettarti immagini identiche da generazioni ripetute.

Mi serve una nuova libreria client?

Non per gli esempi qui riportati. Bastano normali richieste HTTP. Qualunque client tu scelga deve gestire l’invio delle attività e il polling invece di aspettarsi subito un’immagine finita.

Dove trovo il costo finale?

Nello storico di utilizzo dell’account. Un’attività completata può includere il consumo di token, ma la sua risposta pubblica non ha un campo di costo. La guida ai prezzi tratta le stime.

Concludi la migrazione al confine dell’applicazione

Una migrazione di API di immagini è completa quando l’applicazione gestisce l’intero ciclo di vita del risultato: attività accettata, stato di attesa, output finito, download ed errore. Tieni piccola la prima modifica, prova i casi di interruzione e sposta le richieste restanti solo dopo aver verificato i loro presupposti di input e output.