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.

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.