API de generación de imágenes con IA: ejemplo en TypeScript

Una API de generación de imágenes con IA convierte un prompt en una imagen mediante una ejecución programática. Con Pipe2, inicia Image Generator, consulta el ID devuelto y lee la URL de la imagen en los recursos de la ejecución completada. El ejemplo de TypeScript usa la combinación válida de modelo y calidad más barata del catálogo actual.

Generar una imagen con el SDK de TypeScript

Instala @pipe2-ai/sdk, guarda un token de acceso personal de Pipe2 en PIPE2_TOKEN y ejecuta este módulo con Node. El prompt define un sujeto, un entorno y una iluminación para que el primer resultado sea fácil de evaluar.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  model: 'gpt-image-2',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.',
  quality: 'fast',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Image generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

Esta es exactamente la solicitud a la canalización incluida en el programa:

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "gpt-image-2",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.",
    "quality": "fast"
  }
}

La documentación del SDK de TypeScript explica la instalación, la autenticación, las operaciones de canalización, la carga de recursos, las suscripciones y las consultas de créditos.

Entender el flujo de ejecución, consulta y recurso

RunPipeline recibe el slug de la canalización y un objeto JSON de entrada. Devuelve los identificadores de una ejecución asíncrona en vez de mantener la conexión abierta hasta que la imagen esté lista. Conserva run_pipeline.run_id: GetPipelineRun lo utiliza para recuperar el estado más reciente.

El bucle contempla los dos estados finales. Una ejecución completed puede incluir recursos generados y el ejemplo imprime la URL del primero. Una ejecución failed puede incluir error_message; conviene registrarlo junto con el ID. En producción, establece además un tiempo máximo total y considera que una ejecución ausente es un error. Para recibir cambios en tiempo real, el SDK ofrece WatchPipelineRun como iterable asíncrono.

Empezar con la solicitud válida más barata

El ejemplo fija gpt-image-2 con quality: 'fast'. En el catálogo actual de Image Generator es la combinación válida de menor coste y corresponde al nivel de calidad baja del modelo. Sirve para comprobar autenticación, formato, consulta de estado y tratamiento de recursos antes de invertir más créditos en una imagen final.

Fast es una decisión de coste, no una garantía de acabado. Antes de lanzar un volumen mayor, usa EstimatePipelineCost con el mismo pipeline_slug y el mismo input. Repite la estimación cuando cambies el modelo, la calidad o la cantidad de referencias: el catálogo activo determina el cargo real.

Elegir solo los controles necesarios

Un prompt basta para ejecutar la canalización. También puedes añadir imágenes de referencia, un vídeo de referencia compatible, relación de aspecto, calidad, modelo y la preferencia de mejora del prompt. Los límites dependen del modelo, así que consulta el esquema de la canalización en lugar de suponer que todos los motores aceptan los mismos archivos.

Para generar solo desde texto, describe el sujeto, la composición, la luz y el estilo con una breve narración. Escribe entre comillas cualquier texto literal que deba aparecer y revísalo en el resultado. Si aportas referencias, indica la función de cada una y qué rasgos deben mantenerse. Las cinco relaciones de aspecto comunes son 1:1, 16:9, 9:16, 4:3 y 3:4.

Auto permite que Pipe2 elija un motor compatible. Fija un modelo únicamente cuando el producto dependa de una capacidad documentada o quieras hacer una comparación controlada. La comparativa de generadores de imágenes con IA explica cómo mantener constantes el prompt, las referencias, el encuadre y el número de intentos.

Usar la API de Nano Banana Pro con Image Generator

Para acceder a la API de Nano Banana Pro a través de Pipe2, usa la misma canalización image-generator y establece input.model en gemini-3-pro-image. Nano Banana Pro es el nombre del modelo en el catálogo; en la solicitud debes conservar el identificador de Pipe2. Los métodos del SDK, el ID de ejecución, el bucle de consulta y el recurso de imagen devuelto siguen el flujo descrito arriba. Autentícate con tu token de Pipe2.

Para comparar resultados, conserva el prompt del ejemplo y cambia únicamente el modelo. La solicitud existente con GPT Image 2 y calidad fast permite comprobar la integración con un coste menor; antes de ejecutar Nano Banana Pro, estima la solicitud modificada con EstimatePipelineCost. En este modelo, quality: 'fast' selecciona una salida de 1K, mientras que auto o hd seleccionan 2K. Ambos tamaños comparten la misma tarifa, por lo que fast no reduce el precio como lo hace con GPT Image 2. Esta canalización no ofrece salida de 4K para Nano Banana Pro.

Basta con un prompt de texto; también puedes enviar hasta 14 reference_images. Explica en el prompt la función de cada referencia. No envíes reference_videos con este modelo: Nano Banana Pro no admite entrada de vídeo en Image Generator. Establece enhance_prompt en false si quieres conservar el texto original de una solicitud sin referencias. Para una composición precisa, describe la posición de cada elemento, escribe entre comillas el texto literal y revisa la imagen generada antes de usarla.

Usar la API de GPT Image 2 a través de Pipe2

El ejemplo anterior ya permite acceder a GPT Image 2 mediante la API de Pipe2: envía pipeline_slug: 'image-generator' con input.model: 'gpt-image-2' y un prompt de texto. Autentícate con tu token de Pipe2. Guarda el ID devuelto y consulta la ejecución con los mismos métodos del SDK hasta obtener la imagen al completarse; elegir este modelo no cambia el flujo.

Usa quality: 'fast' para el nivel de calidad baja del ejemplo, auto para calidad media o hd para alta. Estos son los valores de entrada de Pipe2: envíalos tal como aparecen, sin sustituirlos por los nombres de los niveles. Estima la solicitud modificada antes de aumentar la calidad. GPT Image 2 admite hasta cinco reference_images y no admite reference_videos en esta canalización. Si añades referencias, explica qué debe aportar cada una y revisa los cambios no deseados, sobre todo en textos y detalles del producto.

Proteger tokens, errores y URL de salida

Crea el cliente con un token de Pipe2 obtenido del entorno de ejecución. No lo escribas en el código fuente, no lo subas al repositorio ni lo muestres en los registros del navegador. La solicitud usa el slug de Pipe2; el cliente no necesita enviar credenciales separadas del proveedor del modelo.

Guarda el ID antes de empezar a consultar para poder reanudar el mismo trabajo si el proceso se reinicia. Trata la URL devuelta como un dato de la aplicación: consérvala si necesitas una referencia duradera, comprueba que exista un recurso antes de leer la posición cero y muestra el error sin reintentar indefinidamente. Aplica también tus reglas habituales de autorización, moderación y conservación a los prompts y archivos de usuarios.