Migrar una API de imágenes a SeedRouter: peticiones y tareas

Migrar una API de imágenes a SeedRouter exige revisar el contrato de petición y respuesta, no solo cambiar la clave de API y la URL base. GPT Image 2 usa campos de generación de imágenes conocidos, pero el envío devuelve un identificador de tarea. Tu aplicación debe guardar ese identificador, sondear hasta que termine y leer las URL de las imágenes finales.

La migración útil más pequeña es una petición de texto a imagen desde código de servidor. Consigue que funcione antes de mover ediciones con referencia, máscaras o un lote mayor. Mantén disponible la integración existente hasta que el nuevo camino supere las mismas comprobaciones de aceptación.

¿Qué supuestos hay que cambiar?

Localiza el código que convierte una petición de imagen en un archivo utilizable. Puede que ahora espere una imagen en la primera respuesta, decodifique un campo base64 o use una subida multipart. Esos supuestos hay que comprobarlos uno a uno frente a la referencia de GPT Image 2 en SeedRouter.

Supuesto actual	Contrato de SeedRouter	Cambio en la aplicación
El envío devuelve la imagen final	El envío devuelve una referencia de tarea	Guardar `id` antes de esperar la salida
La salida está en el array `data` del envío	Las imágenes de tareas completadas están en `output.data`	Leer los resultados tras la finalización
El cliente decodifica `b64_json`	Las imágenes se devuelven como URL alojadas	Descargar las URL devueltas
La edición sube bytes de archivo	Las referencias usan objetos URL en `images`	Hacer accesibles por URL las imágenes de entrada
Una ruta de edición aparte elige la edición	`images` y `mask` determinan la operación	Usar el endpoint público generations
Un tiempo agotado en el cliente significa fallo	La tarea puede seguir en proceso	Reanudar la consulta del identificador guardado

Por eso una llamada síncrona de un SDK de Images no es un reemplazo directo, aunque acepte una URL base configurable. Conserva los ajustes de modelo que sigas necesitando, pero adapta el código de la aplicación que espera y consume el resultado.

Asigna los campos antes de mover código

Empieza por model, prompt, size, quality y n. Usa gpt-image-2 como identificador de modelo. Envía dimensiones explícitas como 1024x1024 o usa auto; no arrastres un campo resolution aparte ni una cadena de proporción como tamaño.

El documento OpenAPI de SeedRouter es un buen apoyo durante la revisión. Compara los campos que tu aplicación envía de verdad, incluidos los valores que añade un SDK, en lugar de revisar solo los argumentos visibles en la llamada. Los campos desconocidos se rechazan.

Para este modelo, style, response_format y un input_fidelity configurable no son campos de petición aceptados. Elimina esos supuestos en lugar de esconderlos dentro de un objeto de opciones genérico. La petición tampoco admite stream ni partial_images; en esta integración el progreso se comunica mediante el estado de la tarea.

Los ajustes de salida tienen dependencias. Si pides transparencia, elige PNG. Envía output_compression solo con JPEG, no con PNG. Un valor de compresión de cero es válido, así que evita una comprobación de veracidad que lo sustituya por un valor por defecto. Son detalles pequeños que una petición básica correcta no llega a ejercitar.

Sustituye el supuesto de respuesta síncrona

El siguiente ejemplo de Node.js envía una petición e imprime su identificador de tarea. Define SEEDROUTER_API_KEY en el servidor; nunca pongas la clave en código de navegador ni en una variable de entorno pública.

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.

Para una prueba manual rápida basta con imprimir el identificador. En una aplicación, guárdalo antes de devolver el control al usuario. Así tu registro de imagen puede quedar pendiente mientras el usuario navega a otra parte, y una comprobación posterior recuperará el resultado.

Consulta el progreso con GET https://api.seedrouter.ai/v1/tasks/{id} y la misma cabecera de autorización. Con completed, lee output.data[].url. Con failed, trata el error documentado y muestra un estado de fallo adecuado. Para un ejemplo ejecutable que conserva el progreso, consulta envío por lotes y sondeo.

No adjuntes la clave de API a la petición de descarga de la imagen. La autorización pertenece a la llamada de la API de tareas, no a una descarga aparte de una URL de recurso devuelta.

Pasa referencias y máscaras a entradas por URL

Un flujo existente basado en archivos locales necesita un paso previo más: dejar la imagen de referencia disponible en una URL HTTP(S) accesible que controles. Pásala como images: [{"image_url": "https://example.com/reference.png"}], sustituyendo esa dirección por la tuya. No envíes rutas de archivo, URL blob:, data URL en base64 ni identificadores de Files.

Comprueba que la URL funciona sin las cookies de sesión de tu navegador. Una URL que solo se abre con tu sesión iniciada no sirve como referencia para esta petición. Mantén la imagen accesible mientras la tarea se procesa; no revoques el acceso justo después de enviarla.

Una máscara se indica con mask: {"image_url": "https://example.com/mask.png"} y requiere imágenes de referencia. Debe coincidir con las dimensiones de la primera imagen de referencia. Revisa todas las restricciones de entradas multimedia antes de mover un flujo de edición existente, en especial formatos y tamaños de archivo.

¿Qué debe cubrir la prueba de aceptación?

Prueba el comportamiento del que depende tu aplicación, incluidas las interrupciones. Una imagen correcta solo demuestra que una petición funcionó. No demuestra que tu estado pendiente sobreviva a una recarga ni que un fallo de descarga evite una generación duplicada.

Enviar una petición solo de texto y guardar el identificador devuelto antes de sondear.
Detener el sondeo, reanudarlo con ese mismo identificador y comprobar que no se produce otro POST.
Tratar processing, completed y failed como estados distintos.
Descargar una imagen completada sin enviar la cabecera de autorización de la API.
Comprobar una edición con referencia usando una URL accesible y después el manejo de fallos con una inaccesible.
Validar los campos opcionales, incluida una compresión a cero, con el esquema publicado.
Confirmar que los cargos de la cuenta se leen del historial de uso y no de un campo de coste inventado en la respuesta de tarea.

Usa respuestas simuladas para pruebas repetibles de fallo y tiempo agotado. Haz una prueba real pequeña y deliberada solo cuando esas comprobaciones pasen; las generaciones reales consumen saldo. Si el resultado del envío es incierto, investiga antes de reintentarlo. Una excepción local no demuestra que no se aceptara ninguna tarea.

Preguntas frecuentes

¿Puedo conservar mis prompts actuales?

Sí, como punto de partida, siempre que cumplan las restricciones de la petición. Conserva unos cuantos prompts representativos para comparar, pero no esperes imágenes idénticas de generaciones repetidas.

¿Necesito una biblioteca cliente nueva?

Para los ejemplos de aquí no. Bastan peticiones HTTP estándar. Sea cual sea el cliente que elijas, debe gestionar el envío de tareas y el sondeo en lugar de esperar una imagen terminada al instante.

¿Dónde veo el coste final?

En el historial de uso de la cuenta. Una tarea completada puede incluir el consumo de tokens, pero su respuesta pública no tiene campo de coste. La guía de precios trata las estimaciones.

Cierra la migración en la frontera de la aplicación

Una migración de API de imágenes está completa cuando la aplicación gestiona todo el ciclo de vida del resultado: tarea aceptada, estado pendiente, salida terminada, descarga y fallo. Mantén pequeño el primer cambio, prueba los casos de interrupción y mueve el resto de peticiones solo después de comprobar sus supuestos de entrada y salida.

Mover una integración de imágenes a SeedRouter