Documentación SDK de la Librería nvidia-node

Overview

Problema

Los desarrolladores necesitan una guía clara y completa para integrar y utilizar eficazmente la librería nvidia-node en sus aplicaciones Node.js para interactuar con las APIs de IA de Nvidia.

Solución Propuesta

Crear una documentación exhaustiva, bien estructurada y fácil de entender que cubra todos los aspectos de la librería, desde la instalación hasta el uso avanzado de sus funcionalidades.

Audiencia Objetivo

Desarrolladores de Node.js de diversos niveles de experiencia.

Propuesta de Valor

Permitir a los desarrolladores maximizar el rendimiento de la librería, reducir el tiempo de integración, comprender las capacidades de los modelos de IA de Nvidia accesibles y solucionar problemas de manera eficiente.

Table of Contents

• Overview
• Propósito de la Librería
• Guía de Inicio Rápido
  • 1. Instalación
  • 2. Configura tu API Key
  • 3. Genera tu primera imagen
  • 4. Ejecuta el ejemplo
• Instalación
  • Requisitos Previos
  • Instalación Básica
  • Dependencias Principales
• Configuración de Variables de Entorno
  • Usando un Archivo .env
  • Estructura del Archivo .env
  • Cargando Variables de Entorno con dotenv
• Clase Principal Nvidia
  • Importación del Cliente
  • Instanciación Básica
  • Opciones del Constructor
  • Ejemplos de Instanciación
• Recurso Images
  • Propósito y Acceso
  • Método images.create()
  • Modelos Soportados
  • Parámetros para el Modelo FLUX
  • Parámetros para Stable Diffusion
  • Estructura de Respuesta
  • Ejemplos Completos de Generación de Imágenes
• Recurso Chat
  • Propósito y Acceso
  • Método chat.completions.create()
  • Modelos Soportados para Chat
  • Parámetros Principales
  • Parámetros Adicionales
  • Estructura de Respuesta para Chat
  • Ejemplos de Chat
• Recurso Embeddings
  • Propósito y Acceso
  • Método embeddings.create()
  • Parámetros de Embeddings
  • Estructura de Respuesta de Embeddings
  • Ejemplo de Uso
• Módulo ImageUtils
  • Función saveBase64ToFile
  • Función generateUniqueFilename
• Manejo de Errores
  • Mecanismos de Manejo de Errores
  • Tipos Comunes de Errores
  • Estructura del Objeto de Error
  • Tips para Debugging
  • Ejemplos de Manejo de Errores
  • Mejores Prácticas para Manejo de Errores
• Uso Básico
• Modelos Soportados y Endpoints
• Desarrollo

Propósito de la Librería

La librería nvidia-node facilita la interacción con los servicios de IA de Nvidia, permitiendo a los desarrolladores integrar capacidades avanzadas de IA, como generación de imágenes, chat, embeddings y procesamiento de video, en sus aplicaciones Node.js de forma sencilla y eficiente.

Guía de Inicio Rápido

Esta guía te ayudará a empezar rápidamente con nvidia-node, desde la instalación hasta generar tu primera imagen con IA.

1. Instalación

Instala la librería y sus dependencias con npm:

npm install nvidia dotenv node-fetch@2

O si prefieres usar yarn:

yarn add nvidia dotenv node-fetch@2

2. Configura tu API Key

Crea un archivo .env en la raíz de tu proyecto:

NVIDIA_API_KEY=tu_api_key_de_nvidia_aquí

3. Genera tu primera imagen

Crea un archivo quick-start.js con el siguiente código:

// Importar dependencias
const { Nvidia, ImageUtils } = require('nvidia-node');
require('dotenv').config();
const fs = require('fs');
const path = require('path');

// Crear una instancia del cliente Nvidia
const nvidia = new Nvidia();

// Función para generar una imagen
async function generarPrimeraImagen() {
  try {
    console.log('Generando imagen con FLUX...');
    
    // Parámetros para la generación
    const params = {
      prompt: 'Un gato adorable con un sombrero pequeño, estilo fotorrealista',
      width: 512,
      height: 512
    };
    
    // Generar la imagen
    const response = await nvidia.images.create('FLUX.1-dev', params);
    
    console.log('¡Imagen generada correctamente!');
    
    // Guardar la imagen en un archivo
    if (response.images && response.images.length > 0) {
      // Crear directorio si no existe
      const outputDir = path.join(__dirname, 'imagenes');
      if (!fs.existsSync(outputDir)) {
        fs.mkdirSync(outputDir, { recursive: true });
      }
      
      // Guardar imagen usando ImageUtils
      const imagePath = await ImageUtils.saveBase64ToFile(
        response.images[0],
        outputDir,
        'mi_primera_imagen.png'
      );
      
      console.log(`Imagen guardada en: ${imagePath}`);
    }
  } catch (error) {
    console.error('Error al generar la imagen:', error.message);
    
    // Verificar problemas comunes
    if (!process.env.NVIDIA_API_KEY) {
      console.error('No se encontró NVIDIA_API_KEY en las variables de entorno');
      console.error('Asegúrate de crear un archivo .env con tu API key');
    }
  }
}

// Ejecutar la función
generarPrimeraImagen();

4. Ejecuta el ejemplo

Guarda el código anterior en un archivo llamado quick-start.js y ejecútalo:

node quick-start.js

Si todo está configurado correctamente, verás un mensaje de éxito y la imagen generada aparecerá en el directorio imagenes/.

Nota: Este ejemplo también está disponible en el directorio examples/quick-start.js de la librería para que puedas ejecutarlo directamente.

Nvidia API Node.js Library (nvidia-node)

Este repositorio contiene una librería cliente Node.js/TypeScript para interactuar con la API de Nvidia, permitiendo un acceso conveniente a modelos de Chat, Embeddings, Generación de Imágenes y Generación de Video. Está inspirada en la estructura de openai-node.

Instalación

Requisitos Previos

• Node.js 14.x o superior
• npm 6.x o superior (o yarn 1.x)
• Una API Key de Nvidia (necesaria para usar los modelos fuera del entorno Nvidia NGC)

Instalación Básica

Puedes instalar la librería usando npm o yarn:

npm install nvidia-node 
# o
yarn add nvidia-node

(Nota: Actualmente, nvidia-node es el nombre que hemos estado usando. Si publicas esto bajo un nombre diferente, actualiza el comando de instalación).

Dependencias Principales

La librería nvidia-node incluye automáticamente las siguientes dependencias principales:

• node-fetch@2: Usado para realizar solicitudes HTTP en entornos Node.js.
• axios: Cliente HTTP para la comunicación con las APIs de Nvidia.
• dotenv: Para cargar variables de entorno desde un archivo .env.

No necesitas instalar estas dependencias manualmente, ya que están incluidas como dependencias directas en el paquete.

Configuración de Variables de Entorno

Para usar nvidia-node correctamente, necesitarás configurar una API key de Nvidia. La forma recomendada de hacerlo es a través de variables de entorno utilizando un archivo .env.

Usando un Archivo .env

El paquete nvidia-node utiliza la biblioteca dotenv para cargar variables de entorno desde un archivo .env ubicado en la raíz de tu proyecto. Esto proporciona una forma segura y conveniente de manejar claves API sin incluirlas directamente en tu código.

Para configurar tu entorno:

1. Crea un archivo .env en la raíz de tu proyecto (al mismo nivel que tu package.json)
2. Añade tu API key de Nvidia en el archivo
3. Asegúrate de incluir el archivo .env en tu .gitignore para no exponer tus claves API en repositorios públicos

Estructura del Archivo .env

Tu archivo .env debería tener la siguiente estructura:

NVIDIA_API_KEY=tu_api_key_de_nvidia_aquí

Si necesitas configurar endpoints personalizados para entornos especiales (como pruebas internas de Nvidia), también puedes agregar:

NVIDIA_AI_API_URL=https://url-personalizada-api-ai
NVIDIA_INTEGRATIONS_API_URL=https://url-personalizada-integrations-api

En la mayoría de los casos, solo necesitarás configurar NVIDIA_API_KEY.

Cargando Variables de Entorno con dotenv

Para cargar las variables de entorno desde el archivo .env en tu aplicación, necesitas utilizar la biblioteca dotenv. A continuación se muestran diferentes formas de hacerlo:

En JavaScript (CommonJS)

// Al inicio de tu archivo principal
require('dotenv').config();

const { Nvidia } = require('nvidia-node');

// La API Key se carga automáticamente desde process.env.NVIDIA_API_KEY
const nvidia = new Nvidia();

// También puedes invalidar la variable de entorno si es necesario
// const nvidia = new Nvidia({ apiKey: 'TU_API_KEY_MANUAL' });

En TypeScript / ESM

// Al inicio de tu archivo principal
import * as dotenv from 'dotenv';
dotenv.config();

import { Nvidia } from 'nvidia-node';

// La API Key se carga automáticamente desde process.env.NVIDIA_API_KEY
const nvidia = new Nvidia();

// También puedes invalidar la variable de entorno si es necesario
// const nvidia = new Nvidia({ apiKey: 'TU_API_KEY_MANUAL' });

En Scripts de Ejemplo

Si estás ejecutando scripts de ejemplo, asegúrate de que dotenv se cargue al inicio, antes de cualquier importación:

// Al principio del script
import * as dotenv from 'dotenv'; 
dotenv.config();

// Resto de las importaciones
import { Nvidia } from 'nvidia-node';
import * as fs from 'fs';
import * as path from 'path';

async function main() {
  // La API Key se carga automáticamente desde process.env.NVIDIA_API_KEY
  const nvidia = new Nvidia();
  
  // Si process.env.NVIDIA_API_KEY no está definido, muestra un error útil
  if (!nvidia.apiKey) {
    console.error('Error: No se encontró NVIDIA_API_KEY en las variables de entorno.');
    console.error('Crea un archivo .env con NVIDIA_API_KEY=tu_api_key_aquí');
    return;
  }
  
  // Resto del código...
}

main().catch(err => console.error('Error:', err));

La librería nvidia-node está diseñada para buscar automáticamente la variable de entorno NVIDIA_API_KEY si no se proporciona una API Key explícitamente en el constructor. Esto hace que tu código sea más limpio y seguro, especialmente para repositorios compartidos.

Clase Principal Nvidia

La clase Nvidia es el punto de entrada principal para interactuar con todas las funcionalidades de la API de Nvidia. Esta clase gestiona la autenticación, las configuraciones de conexión y proporciona acceso a los distintos recursos disponibles, como imágenes, chat, embeddings y video.

Importación del Cliente

Para utilizar la librería nvidia-node, primero debes importar la clase Nvidia en tu código. Dependiendo de tu entorno, puedes hacerlo de una de las siguientes maneras:

En JavaScript (CommonJS)

// Importación en JavaScript usando sintaxis CommonJS
const { Nvidia } = require('nvidia-node');

En TypeScript / ESM (ECMAScript Modules)

// Importación en TypeScript o JavaScript moderno usando ESM
import { Nvidia } from 'nvidia-node';

Instanciación Básica

Una vez importada la clase, puedes crear una instancia del cliente de Nvidia de manera muy sencilla:

// Instanciación básica (utilizando NVIDIA_API_KEY de las variables de entorno)
const nvidia = new Nvidia();

Este método de instanciación asume que ya has configurado la variable de entorno NVIDIA_API_KEY como se describió en la sección de Configuración de Variables de Entorno.

Si prefieres proporcionar tu API key directamente en el código (no recomendado para entornos de producción por razones de seguridad), puedes hacerlo de la siguiente manera:

// Instanciación con API key explícita
const nvidia = new Nvidia({
  apiKey: 'tu_api_key_de_nvidia_aquí'
});

Una vez que hayas instanciado el cliente, tendrás acceso a todos los recursos disponibles a través de propiedades bien organizadas:

// Acceso a recursos específicos
const imagesResource = nvidia.images;    // Para generación de imágenes
const chatResource = nvidia.chat;        // Para completaciones de chat
const embeddingsResource = nvidia.embeddings;  // Para creación de embeddings
const videoResource = nvidia.video;      // Para generación de video

Cada recurso proporciona métodos específicos para interactuar con las diferentes funcionalidades de la API de Nvidia.

Opciones del Constructor

La clase Nvidia acepta un objeto de opciones que te permite personalizar el comportamiento del cliente. A continuación se detallan todas las opciones disponibles:

| Opción | Tipo | Descripción | Valor por defecto | |--------|------|-------------|-------------------| | apiKey | string | Tu API key de Nvidia para autenticación. | process.env.NVIDIA_API_KEY | | baseURLAI | string | URL base para las APIs del catálogo de IA (imágenes, video). | "https://ai.api.nvidia.com/v1/genai" | | baseURLIntegrate | string | URL base para las APIs de Integrate (chat, embeddings). | "https://integrate.api.nvidia.com/v1" | | timeout | number | Tiempo máximo de espera para las solicitudes en milisegundos. | 60000 (60 segundos) |

apiKey

La clave de API de Nvidia utilizada para autenticar las solicitudes a la API. Si no se proporciona, el cliente intentará usar el valor de la variable de entorno NVIDIA_API_KEY.

const nvidia = new Nvidia({
  apiKey: 'tu_api_key_de_nvidia_aquí'
});

baseURLAI

La URL base para las APIs del catálogo de IA, que incluyen servicios como generación de imágenes y video. Solo necesitas modificar este valor si estás utilizando un punto de conexión personalizado o si Nvidia cambia su URL base oficial.

const nvidia = new Nvidia({
  baseURLAI: 'https://tu-url-personalizada-ai.ejemplo.com/v1/genai'
});

baseURLIntegrate

La URL base para las APIs de Integrate, que incluyen servicios como chat y embeddings. Solo necesitas modificar este valor si estás utilizando un punto de conexión personalizado o si Nvidia cambia su URL base oficial.

const nvidia = new Nvidia({
  baseURLIntegrate: 'https://tu-url-personalizada-integrate.ejemplo.com/v1'
});

timeout

El tiempo máximo (en milisegundos) que el cliente esperará para una respuesta de la API antes de cancelar la solicitud. Esto es útil para manejar conexiones lentas o cuando se procesan solicitudes que pueden tardar más tiempo, como la generación de imágenes o videos complejos.

const nvidia = new Nvidia({
  timeout: 120000  // 2 minutos en lugar del valor predeterminado de 1 minuto
});

Ejemplos de Instanciación

A continuación, se presentan varios ejemplos completos de instanciación del cliente Nvidia para diferentes escenarios:

Ejemplo 1: Instanciación básica con variable de entorno

Este es el enfoque más sencillo y recomendado para la mayoría de los casos:

import { Nvidia } from 'nvidia-node';

// Usando la variable de entorno NVIDIA_API_KEY
const nvidia = new Nvidia();

Ejemplo 2: Instanciación con API key explícita

Este enfoque es útil para pruebas o cuando necesitas usar diferentes API keys en el mismo código:

import { Nvidia } from 'nvidia-node';

// Especificar API key directamente
const nvidia = new Nvidia({
  apiKey: 'tu_api_key_de_nvidia_aquí'
});

Ejemplo 3: Personalización completa

Para casos avanzados donde necesitas personalizar todos los parámetros disponibles:

import { Nvidia } from 'nvidia-node';

// Personalización completa del cliente
const nvidia = new Nvidia({
  apiKey: 'tu_api_key_de_nvidia_aquí',
  baseURLAI: 'https://tu-url-personalizada-ai.ejemplo.com/v1/genai',
  baseURLIntegrate: 'https://tu-url-personalizada-integrate.ejemplo.com/v1',
  timeout: 180000  // 3 minutos
});

Ejemplo 4: Instanciación en un entorno serverless

En entornos serverless como AWS Lambda o Vercel Functions, a menudo necesitas optimizar el timeout para que se ajuste a los límites de la plataforma:

import { Nvidia } from 'nvidia-node';

// Configuración optimizada para entornos serverless
const nvidia = new Nvidia({
  apiKey: process.env.NVIDIA_API_KEY,
  timeout: 25000  // 25 segundos para mantenerse dentro de límites típicos de funciones serverless
});

Ejemplo 5: Uso en aplicaciones con múltiples clientes

Si tu aplicación necesita interactuar con diferentes cuentas de Nvidia simultáneamente:

import { Nvidia } from 'nvidia-node';

// Cliente para generación de imágenes (con una cuenta)
const imageClient = new Nvidia({
  apiKey: process.env.NVIDIA_IMAGE_API_KEY
});

// Cliente para chat y LLMs (con otra cuenta)
const chatClient = new Nvidia({
  apiKey: process.env.NVIDIA_CHAT_API_KEY
});

// Uso
async function processRequests() {
  const imageResponse = await imageClient.images.create('FLUX.1-dev', { /* parámetros */ });
  const chatResponse = await chatClient.chat.completions.create({ /* parámetros */ });
  
  // Procesar respuestas...
}

Ejemplo 6: Manejo de errores en la instanciación

Es una buena práctica manejar posibles errores en la instanciación, especialmente cuando dependes de variables de entorno:

import { Nvidia } from 'nvidia-node';

let nvidia;

try {
  nvidia = new Nvidia();
  
  // Verificar que la API key está disponible
  if (!nvidia.apiKey) {
    throw new Error('No se ha proporcionado la API key de Nvidia');
  }
  
  console.log('Cliente de Nvidia inicializado correctamente');
} catch (error) {
  console.error('Error al inicializar el cliente de Nvidia:', error.message);
  // Manejar el error según la necesidad de tu aplicación
  // Por ejemplo: process.exit(1) para terminar la aplicación, o proporcionar una clave de prueba
}

Estos ejemplos cubren la mayoría de los escenarios comunes para instanciar el cliente de Nvidia. Recuerda que, como mejor práctica de seguridad, es recomendable siempre utilizar variables de entorno para las claves API, especialmente en entornos de producción.

Recurso Images

El recurso Images es uno de los componentes principales de la librería nvidia-node, diseñado específicamente para interactuar con los modelos de generación de imágenes de Nvidia. Este recurso te permite crear imágenes impresionantes basadas en descripciones textuales (prompts) o modificar imágenes existentes.

Propósito y Acceso

Propósito

El recurso Images proporciona una interfaz simplificada para:

• Generación de imágenes basadas en texto: Crear imágenes completamente nuevas a partir de descripciones textuales.
• Estilización: Aplicar estilos específicos a imágenes generadas.
• Personalización avanzada: Controlar parámetros como el tamaño de la imagen, la semilla para reproducibilidad, y la fuerza de adherencia al prompt.
• Acceso a múltiples modelos: Utilizar distintos modelos de generación de imágenes según tus necesidades.

Acceso

Para acceder al recurso Images, primero debes crear una instancia del cliente Nvidia como se describe en secciones anteriores. Una vez que tengas una instancia del cliente, puedes acceder al recurso Images a través de la propiedad images:

import { Nvidia } from 'nvidia-node';

// Crear instancia del cliente Nvidia
const nvidia = new Nvidia();

// Acceder al recurso Images
const imagesResource = nvidia.images;

El recurso Images proporciona todos los métodos necesarios para trabajar con la generación de imágenes basada en IA. El método principal que utilizarás es create(), que permite generar imágenes utilizando diferentes modelos.

Método images.create()

El método create() es la función principal para generar imágenes con la API de Nvidia. Este método toma dos parámetros fundamentales:

images.create(modelPath, params)

Firma del Método

async create(modelPath: string, params: ImageCreateParams): Promise<ImageCreateResponse>

• Retorno: Promesa que resuelve a un objeto ImageCreateResponse que contiene la imagen generada (típicamente en formato base64) y metadatos adicionales.

Parámetros

modelPath

El parámetro modelPath es una cadena de texto que identifica el modelo específico de generación de imágenes que quieres utilizar. Este parámetro es crucial porque determina:

• El tipo de modelo que procesará tu solicitud
• Las capacidades y limitaciones de la generación
• La calidad y estilo de las imágenes resultantes
• Los parámetros específicos que puedes utilizar en el objeto params

La estructura del modelPath generalmente sigue el formato proveedor/nombre-del-modelo, por ejemplo:

// Usando el modelo FLUX de Nvidia
const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Un paisaje futurista de una ciudad con rascacielos y vehículos voladores, estilo fotorrealista',
  seed: 12345,
  num_images: 1
});

// Usando Stable Diffusion XL
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  prompt: 'Un astronauta en una selva tropical, estilo fotorrealista'
});

El modelPath actúa como un selector del modelo específico en la infraestructura de Nvidia, dirigiendo tu solicitud al endpoint correcto y al modelo apropiado. Cada modelo tiene diferentes capacidades, velocidades de procesamiento y calidades de salida. En la sección Modelos Soportados se detalla una lista de los modelos disponibles.

params

El segundo parámetro es un objeto que contiene todos los parámetros de configuración para la generación de la imagen. Estos parámetros varían según el modelo seleccionado, pero algunos comunes incluyen:

• prompt: La descripción textual de la imagen a generar
• negative_prompt: Lo que no quieres ver en la imagen (para algunos modelos)
• height y width: Dimensiones de la imagen a generar
• seed: Para reproducibilidad de resultados
• num_images: Número de imágenes a generar en una sola llamada (cuando el modelo lo permite)

Cada modelo tiene su propio conjunto de parámetros aceptados, que están tipificados en la librería para facilitar su uso. Los tipos específicos para cada modelo se detallarán en una sección posterior de esta documentación.

Ejemplo Básico

import { Nvidia } from 'nvidia-node';
import * as fs from 'fs';

async function generateImage() {
  const nvidia = new Nvidia();
  
  try {
    // Generar una imagen usando el modelo FLUX de Nvidia
    const response = await nvidia.images.create('FLUX.1-dev', {
      prompt: 'Un castillo medieval en la cima de una montaña con nubes dramáticas',
      seed: 42,  // Opcional: para reproducibilidad
      num_images: 1  // Opcional: cantidad de imágenes a generar
    });
    
    // La respuesta contiene la imagen en base64
    if (response.images && response.images.length > 0) {
      // Extraer la parte de datos en base64 (sin el prefijo data:image/...)
      const base64Data = response.images[0].replace(/^data:image\/\w+;base64,/, '');
      
      // Guardar la imagen en un archivo
      fs.writeFileSync('imagen_generada.png', Buffer.from(base64Data, 'base64'));
      console.log('Imagen guardada como imagen_generada.png');
      
      // También podemos acceder a otros metadatos
      console.log('Seed utilizada:', response.seed);
    }
  } catch (error) {
    console.error('Error al generar la imagen:', error);
  }
}

generateImage();

En la siguiente sección, detallaremos los modelos actualmente soportados por la API de Nvidia y accesibles a través de esta librería.

Modelos Soportados

La API de Nvidia ofrece acceso a varios modelos de generación de imágenes de alta calidad. Cada modelo tiene características y capacidades diferentes, y el parámetro modelPath que utilizas en el método images.create() determina qué modelo procesará tu solicitud.

Modelos Principales

| ModelPath | Descripción | Resoluciones Soportadas | Capacidades Especiales | |-----------|-------------|-------------------------|------------------------| | FLUX.1-dev | Modelo FLUX de Nvidia, optimizado para calidad fotorrealista | Hasta 1024x1024 | Excelente reproducción de detalles, alta fidelidad fotorrealista | | stabilityai/stable-diffusion-xl | Stable Diffusion XL, modelo potente y versátil | Hasta 1024x1024 | Gran interpretación de prompts, estilos artísticos variados |

FLUX.1-dev

El modelo FLUX es un modelo de generación de imágenes de última generación desarrollado por Nvidia. Está optimizado para producir imágenes de aspecto fotorrealista con alta fidelidad y detalles impresionantes.

// Ejemplo de uso del modelo FLUX
const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Paisaje futurista de una ciudad con rascacielos y vehículos voladores, estilo fotorrealista',
  seed: 12345,
  num_images: 1
});

Parámetros específicos aceptados:

• prompt: (Requerido) Descripción textual de la imagen a generar
• seed: (Opcional) Valor numérico para reproducibilidad
• num_images: (Opcional) Número de imágenes a generar (generalmente entre 1-4)

stabilityai/stable-diffusion-xl

Stable Diffusion XL es un modelo avanzado creado por Stability AI, conocido por su versatilidad y capacidad para interpretar prompts complejos con alta calidad. Es especialmente bueno para diferentes estilos artísticos.

// Ejemplo de uso de Stable Diffusion XL
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  prompt: 'Un astronauta montando un caballo en Marte, estilo pintura al óleo',
  negative_prompt: 'baja calidad, borroso',
  width: 1024,
  height: 768,
  seed: 42
});

Parámetros específicos aceptados:

• prompt: (Requerido) Descripción textual de la imagen a generar
• negative_prompt: (Opcional) Descripción de elementos a evitar en la imagen
• width: (Opcional) Ancho de la imagen, valores típicos: 512, 768, 1024
• height: (Opcional) Alto de la imagen, valores típicos: 512, 768, 1024
• seed: (Opcional) Valor numérico para reproducibilidad
• guidance_scale: (Opcional) Número que determina cuánto debe adherirse el modelo al prompt (generalmente entre 1.0-20.0)

Cómo Elegir el Modelo Adecuado

Para elegir el modelo más adecuado para tu caso de uso, considera estos factores:

1. Tipo de contenido:

   • Para imágenes fotorrealistas: FLUX.1-dev
   • Para estilos artísticos variados: stabilityai/stable-diffusion-xl

2. Complejidad del prompt:

   • Prompts detallados y específicos: Ambos modelos funcionan bien, pero SDXL puede manejar instrucciones más complejas

3. Velocidad vs calidad:

   • Mayor velocidad: Depende de la carga de los servidores de Nvidia
   • Mayor calidad: FLUX.1-dev generalmente produce resultados más refinados

4. Modificaciones y control:

   • Control fino mediante negative_prompt: stabilityai/stable-diffusion-xl
   • Control de aspectos específicos: Ambos soportan seed para reproducibilidad

Nvidia actualiza regularmente los modelos disponibles, por lo que esta lista puede ampliarse con el tiempo. Consulta la documentación oficial de Nvidia para conocer los modelos más recientes.

Parámetros para el Modelo FLUX

El modelo FLUX de Nvidia (FLUX.1-dev) acepta un conjunto específico de parámetros a través de la interfaz ImageCreateFluxParams. A continuación se detallan todos los parámetros disponibles, su tipo de dato, si son requeridos u opcionales, y una explicación de su efecto en la imagen generada.

Parámetros Básicos

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | prompt | string | Sí | - | Descripción textual de la imagen que deseas generar. Puede ser detallada e incluir estilos, ambientación, iluminación, etc. | | seed | number | No | Aleatorio | Valor numérico que determina la inicialización del generador aleatorio. Usar el mismo seed con los mismos parámetros producirá resultados similares. | | num_images | number | No | 1 | Número de imágenes a generar en una sola solicitud. Valores típicos: 1-4. A mayor número, mayor tiempo de procesamiento. |

Parámetros de Control de Imagen

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | mode | string | No | 'base' | Modo de generación de imagen. Opciones:- 'base': Generación desde cero basada solo en el prompt- 'canny': Generación guiada por bordes (requiere parámetro image)- 'depth': Generación guiada por mapa de profundidad (requiere parámetro image) | | image | string | No* | - | Imagen en formato base64 para los modos 'canny' y 'depth'. *Requerido solo cuando mode es 'canny' o 'depth'. | | steps | number | No | 20 | Número de pasos de inferencia. A más pasos, mayor calidad pero mayor tiempo de procesamiento. Rango recomendado: 20-50. | | cfg_scale | number | No | 7.0 | Classifier Free Guidance scale. Controla cuánto debe adherirse el modelo al prompt. Valores más altos (8-15) priorizan seguir el prompt, mientras que valores más bajos (4-7) permiten más creatividad. |

Parámetros de Dimensiones

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | width | number | No | 1024 | Ancho de la imagen generada en píxeles. Valores permitidos: 512, 768, 1024. | | height | number | No | 1024 | Alto de la imagen generada en píxeles. Valores permitidos: 512, 768, 1024. |

Ejemplos de Uso

Ejemplo básico:

// Generación básica con FLUX
const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Un paisaje futurista de una ciudad con rascacielos de cristal y vehículos voladores, estilo fotorrealista, iluminación dramática, hora dorada',
  seed: 12345
});

Ejemplo con todos los parámetros:

// Generación avanzada con FLUX
const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Retrato detallado de un lobo ártico, pelaje blanco con detalles finos, ojos azules intensos, ambiente nevado, iluminación lateral',
  mode: 'base',
  steps: 30,
  seed: 42,
  cfg_scale: 8.5,
  width: 1024,
  height: 768,
  num_images: 2
});

Ejemplo con modo canny (generación guiada por bordes):

// Leer imagen desde un archivo y convertir a base64
import * as fs from 'fs';

// Leer la imagen y convertirla a base64
const imageBuffer = fs.readFileSync('imagen_referencia.jpg');
const base64Image = `data:image/jpeg;base64,${imageBuffer.toString('base64')}`;

// Generación con modo canny
const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Paisaje montañoso con cielo dramático, estilo fotorrealista',
  mode: 'canny',
  image: base64Image,
  steps: 25,
  seed: 12345
});

Recomendaciones para el Modelo FLUX

1. Prompts detallados: El modelo FLUX responde muy bien a prompts detallados que incluyan estilo, iluminación, ambiente y detalles específicos.

2. Experimentación con cfg_scale: Valores entre 7-9 suelen producir buenos resultados. Valores más bajos (4-6) permiten más "creatividad" del modelo, mientras que valores más altos (10-15) hacen que el modelo se adhiera más estrictamente al prompt.

3. Dimensiones óptimas: Para obtener los mejores resultados en términos de calidad y tiempo de procesamiento, se recomiendan dimensiones de 1024x1024.

4. Uso del parámetro seed: Si encuentras una imagen que te gusta y quieres generar variaciones similares, guarda el valor de seed de la respuesta y reutilízalo en futuras solicitudes con pequeñas modificaciones en el prompt.

5. Guardado de resultados: Las imágenes en la respuesta vienen en formato base64. Para guardarlas, necesitarás convertirlas a un formato de archivo (como PNG o JPEG).

Parámetros para Stable Diffusion

El modelo Stable Diffusion XL (stabilityai/stable-diffusion-xl) de Stability AI, accesible a través de la API de Nvidia, utiliza un conjunto específico de parámetros mediante la interfaz ImageCreateStableDiffusionParams. A continuación se detallan todos los parámetros disponibles para este modelo, su tipo de dato, obligatoriedad y una explicación de su efecto en la imagen generada.

Parámetros Básicos

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | text_prompts | Array<{text: string, weight?: number}> | Sí | - | Array de objetos que contienen el texto del prompt y un peso opcional. Los prompts con peso positivo indican lo que se desea en la imagen, mientras que los prompts con peso negativo actúan como "negative prompts". | | seed | number | No | Aleatorio | Valor numérico que determina la inicialización del generador aleatorio. Usar el mismo seed con los mismos parámetros producirá resultados similares. |

Parámetros de Control de Imagen

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | sampler | string | No | 'DDIM' | Algoritmo de muestreo a utilizar. Opciones disponibles: 'DDIM', 'DDPM', 'K_EULER', 'K_EULER_ANCESTRAL', 'K_HEUN', 'K_DPM_2', 'K_DPM_2_ANCESTRAL', 'K_LMS'. | | steps | number | No | 50 | Número de pasos de inferencia. Mayor número de pasos generalmente produce imágenes de mayor calidad a costa de mayor tiempo de procesamiento. Rango recomendado: 30-70. | | cfg_scale | number | No | 7.0 | Classifier Free Guidance scale. Controla cuánto debe adherirse el modelo al prompt. Valores más altos (8-15) siguen más estrictamente el prompt, mientras que valores más bajos permiten más libertad creativa. | | init_image | string | No | - | Imagen en formato base64 para servir como base o guía para la generación (funcionalidad de imagen a imagen). | | init_image_mode | string | No | 'IMAGE_STRENGTH' | Modo de uso de la imagen inicial. Opciones: 'IMAGE_STRENGTH', 'STEP_SCHEDULE'. | | image_strength | number | No | 0.35 | Cuando se usa init_image, determina cuánto de la imagen original se preserva. Valores más bajos preservan más detalles de la imagen original. Rango: 0-1. | | step_schedule_start | number | No | 0.65 | Cuando init_image_mode es 'STEP_SCHEDULE', define el inicio del programa de pasos. | | step_schedule_end | number | No | 0.85 | Cuando init_image_mode es 'STEP_SCHEDULE', define el final del programa de pasos. |

Parámetros de Dimensiones y Salida

| Parámetro | Tipo | Requerido | Valor por Defecto | Descripción | |-----------|------|-----------|-------------------|-------------| | width | number | No | 1024 | Ancho de la imagen generada en píxeles. Para SDXL, los valores óptimos son 1024x1024, pero también soporta otras dimensiones múltiplos de 8. | | height | number | No | 1024 | Alto de la imagen generada en píxeles. Para SDXL, los valores óptimos son 1024x1024, pero también soporta otras dimensiones múltiplos de 8. | | samples | number | No | 1 | Número de imágenes a generar en una sola solicitud. | | style_preset | string | No | - | Preset de estilo predefinido para aplicar a la generación. Opciones incluyen 'photographic', '3d-model', 'analog-film', 'anime', 'cinematic', 'comic-book', 'digital-art', 'enhance', 'fantasy-art', 'isometric', 'line-art', 'low-poly', 'modeling-compound', 'neon-punk', 'origami', 'pixel-art', 'tile-texture'. |

Ejemplos de Uso

Ejemplo básico:

// Generación básica con Stable Diffusion XL
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  text_prompts: [
    { text: 'Un gato siamés sentado en el alféizar de una ventana, luz natural, fotorrealista' }
  ],
  seed: 12345
});

Ejemplo con prompts positivos y negativos:

// Generación con prompts positivos y negativos
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  text_prompts: [
    { text: 'Fotografía de un bosque de pinos en otoño, luz dorada, niebla sutil, fotorrealista', weight: 1.0 },
    { text: 'desenfoques, distorsión, baja calidad, pixelado, ruido, artefactos, sobresaturado', weight: -1.0 }
  ],
  cfg_scale: 10,
  steps: 40,
  seed: 42,
  width: 1024,
  height: 768,
  samples: 1
});

Ejemplo con imagen a imagen (image to image):

// Leer imagen desde un archivo y convertir a base64
import * as fs from 'fs';

// Leer la imagen y convertirla a base64
const imageBuffer = fs.readFileSync('imagen_base.jpg');
const base64Image = `data:image/jpeg;base64,${imageBuffer.toString('base64')}`;

// Generación con imagen inicial (image to image)
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  text_prompts: [
    { text: 'El mismo paisaje pero en invierno, con nieve y cielo nublado', weight: 1.0 }
  ],
  init_image: base64Image,
  image_strength: 0.4,  // Preservar 60% de la imagen original
  steps: 50,
  seed: 12345
});

Ejemplo con estilo predefinido (style preset):

// Generación con estilo predefinido
const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  text_prompts: [
    { text: 'Un dragón volando sobre un castillo medieval', weight: 1.0 }
  ],
  style_preset: 'fantasy-art',
  cfg_scale: 8.0,
  steps: 45,
  seed: 42,
  width: 1024,
  height: 1024,
  samples: 1
});

Recomendaciones para Stable Diffusion XL

1. Prompts detallados y negativos: SDXL funciona especialmente bien con prompts detallados y el uso de prompts negativos para evitar elementos no deseados. Aprovecha el sistema de pesos para dar más importancia a ciertos elementos.

2. Experimentación con samplers: Diferentes samplers pueden producir resultados estéticamente distintos:

   • K_EULER_ANCESTRAL: Suele generar resultados más creativos y variados.
   • DDIM: Generalmente más estable y predecible.
   • K_DPM_2_ANCESTRAL: Buen equilibrio entre detalle y creatividad.

3. Ajuste de cfg_scale: Valores entre 7-10 suelen producir buenos resultados. Para arte más abstracto o creativo, prueba valores más bajos (4-6). Para adherirse estrictamente al prompt, usa valores más altos (10-15).

4. Imagen a imagen: Para modificar imágenes existentes, experimenta con diferentes valores de image_strength. Valores más cercanos a 0 preservan más la imagen original, mientras que valores cercanos a 1 permiten más cambios basados en el prompt.

5. Style presets: Los presets de estilo pueden ayudar a dirigir la estética sin necesidad de prompts complejos. Son especialmente útiles cuando buscas un estilo visual específico como "pixel-art" o "fantasy-art".

6. Dimensiones óptimas: Aunque SDXL puede generar imágenes en varias dimensiones, funciona mejor con proporciones estándar como 1:1 (1024x1024), 4:3 (1024x768) o 3:4 (768x1024).

Estructura de Respuesta

Al utilizar el método images.create(), recibirás una respuesta que contiene la imagen generada y metadatos adicionales. Esta respuesta se estructura mediante la interfaz ImageCreateResponse. Es importante entender esta estructura para acceder correctamente a las imágenes generadas y utilizar la información adicional proporcionada.

Estructura del Objeto ImageCreateResponse

La estructura exacta del objeto de respuesta puede variar ligeramente según el modelo utilizado, pero generalmente incluye los siguientes campos:

| Campo | Tipo | Descripción | Modelo | |-------|------|-------------|--------| | images | Array | Array de strings en formato base64 que representan las imágenes generadas. Cada string incluye el prefijo data:image/png;base64,. | FLUX.1-dev | | image_base64 | string | String en formato base64 que representa la imagen generada (con prefijo). Se usa en algunos modelos en lugar del array images. | Algunos modelos | | artifacts | Array<{base64: string, ...}> | Array de objetos, cada uno con una propiedad base64 que contiene una imagen generada y posibles metadatos adicionales. | Algunos modelos | | seed | number | La semilla utilizada para la generación. Útil para reproducir resultados similares. | FLUX.1-dev, SDXL | | finish_reason | string | Razón por la que se completó la generación (ej: 'SUCCESS', 'ERROR'). | Común | | model | string | El modelo utilizado para la generación. | Común | | created_at | string | Timestamp que indica cuándo se generó la imagen. | Algunos modelos | | id | string | Identificador único de la generación. | Algunos modelos |

Acceso a las Imágenes Generadas

Dependiendo del modelo utilizado, podrás acceder a las imágenes generadas de diferentes maneras:

Para FLUX.1-dev:

const response = await nvidia.images.create('FLUX.1-dev', {
  prompt: 'Un paisaje de montañas al atardecer'
});

// Acceder a la primera imagen generada
if (response.images && response.images.length > 0) {
  const imageBase64 = response.images[0];
  // Usar la imagen (guardarla, mostrarla, etc.)
}

// Acceder a múltiples imágenes si se solicitaron con num_images > 1
if (response.images && response.images.length > 1) {
  response.images.forEach((imageBase64, index) => {
    console.log(`Imagen ${index + 1} generada correctamente`);
    // Procesar cada imagen...
  });
}

Para Stable Diffusion:

const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', {
  text_prompts: [{ text: 'Un dragón volando sobre un castillo' }]
});

// Estilo 1: A través del array artifacts
if (response.artifacts && response.artifacts.length > 0) {
  response.artifacts.forEach((artifact, index) => {
    const imageBase64 = artifact.base64;
    // Usar la imagen...
  });
}

// Estilo 2: Directamente desde image_base64 (para algunos modelos/versiones API)
if (response.image_base64) {
  const imageBase64 = response.image_base64;
  // Usar la imagen...
}

Guardado de Imágenes en Disco

Para guardar las imágenes generadas en disco, puedes utilizar el siguiente código:

import * as fs from 'fs';
import * as path from 'path';

// Función auxiliar para guardar una imagen base64 como archivo
function saveBase64Image(base64Data: string, filePath: string): void {
  // Eliminar el prefijo de datos (ej: "data:image/png;base64,")
  const data = base64Data.replace(/^data:image\/\w+;base64,/, '');
  
  // Crear el buffer y guardar el archivo
  const buffer = Buffer.from(data, 'base64');
  fs.writeFileSync(filePath, buffer);
  
  console.log(`Imagen guardada en: ${filePath}`);
}

// Ejemplo de uso con FLUX
async function generateAndSaveImage(): Promise<void> {
  const nvidia = new Nvidia();
  
  try {
    // Generar la imagen
    const response = await nvidia.images.create('FLUX.1-dev', {
      prompt: 'Un hermoso paisaje marino al atardecer',
      seed: 12345
    });
    
    // Verificar que hay imágenes en la respuesta
    if (response.images && response.images.length > 0) {
      // Crear un nombre de archivo único con timestamp
      const timestamp = Date.now();
      const outputPath = path.join(__dirname, 'outputs', `generated_image_${timestamp}.png`);
      
      // Asegurar que el directorio existe
      const outputDir = path.dirname(outputPath);
      if (!fs.existsSync(outputDir)) {
        fs.mkdirSync(outputDir, { recursive: true });
      }
      
      // Guardar la imagen
      saveBase64Image(response.images[0], outputPath);
      
      console.log(`Seed utilizada: ${response.seed}`);
    } else {
      console.log('No se generaron imágenes en la respuesta');
    }
  } catch (error) {
    console.error('Error al generar o guardar la imagen:', error);
  }
}

generateAndSaveImage();

Uso de la Semilla (Seed) para Reproducibilidad

El campo seed en la respuesta es muy útil para reproducir o crear variaciones de imágenes generadas:

async function generateSimilarImages(): Promise<void> {
  const nvidia = new Nvidia();
  const basePrompt = 'Un castillo medieval en un acantilado';
  
  try {
    // Generamos una primera imagen
    const response1 = await nvidia.images.create('FLUX.1-dev', {
      prompt: basePrompt
    });
    
    if (response1.images && response1.images.length > 0 && response1.seed) {
      console.log(`Imagen original generada con seed: ${response1.seed}`);
      
      // Generamos una segunda imagen usando la misma seed para obtener un resultado similar
      const response2 = await nvidia.images.create('FLUX.1-dev', {
        prompt: basePrompt + ', iluminación al atardecer',  // Ligera variación en el prompt
        seed: response1.seed  // Reutilizamos la misma seed
      });
      
      if (response2.images && response2.images.length > 0) {
        console.log('Variación generada con éxito usando la misma seed');
        
        // Aquí podrías guardar ambas imágenes para comparar los resultados
      }
    }
  } catch (error) {
    console.error('Error al generar imágenes:', error);
  }
}

Manejo de Errores

Es importante manejar correctamente los errores al interactuar con las APIs de generación de imágenes:

async function generateImageWithErrorHandling(): Promise<void> {
  const nvidia = new Nvidia();
  
  try {
    const response = await nvidia.images.create('FLUX.1-dev', {
      prompt: 'Un paisaje urbano futurista'
    });
    
    if (response.finish_reason === 'ERROR') {
      console.error('La generación terminó con un error:', response);
      return;
    }
    
    if (!response.images || response.images.length === 0) {
      console.error('No se generaron imágenes en la respuesta');
      return;
    }
    
    // Procesar la imagen normalmente...
    console.log('Imagen generada correctamente');
    
  } catch (error) {
    if (error.response) {
      // Error con respuesta de la API
      console.error(`Error de API: ${error.response.status}`);
      console.error('Detalles:', error.response.data);
    } else if (error.request) {
      // Error de red o sin respuesta
      console.error('Error de red o timeout. La solicitud fue enviada pero no se recibió respuesta.');
      console.error('Es posible que el modelo esté sobrecargado o que la API esté experimentando problemas.');
    } else {
      // Otros errores
      console.error(`Error: ${error.message}`);
    }
  }
}

Estos ejemplos te permiten entender la estructura de las respuestas de images.create() y cómo procesar eficazmente las imágenes generadas. En la siguiente sección, proporcionaremos ejemplos completos para generar imágenes tanto con FLUX como con Stable Diffusion.

Ejemplos Completos de Generación de Imágenes

Para ayudarte a integrar rápidamente la generación de imágenes en tus aplicaciones, a continuación presentamos ejemplos completos y listos para usar con los modelos de generación de imágenes más populares de Nvidia.

Ejemplo 1: Generación de Imágenes con FLUX

Este ejemplo muestra el proceso completo de generar una imagen usando el modelo FLUX.1-dev, incluyendo la configuración del cliente, manejo de errores, creación de directorios, guardado de la imagen y opciones avanzadas.

// generador-flux.ts
import * as dotenv from 'dotenv';
import * as fs from 'fs';
import * as path from 'path';
import { Nvidia } from 'nvidia-node';

// Cargar variables de entorno desde .env
dotenv.config();

/**
 * Función para guardar una imagen en formato base64 como archivo
 */
function saveBase64Image(base64Data: string, filePath: string): void {
  // Eliminar el prefijo de datos si existe
  const data = base64Data.replace(/^data:image\/\w+;base64,/, '');
  
  // Crear el buffer y guardar el archivo
  const buffer = Buffer.from(data, 'base64');
  fs.writeFileSync(filePath, buffer);
  
  console.log(`Imagen guardada en: ${filePath}`);
}

/**
 * Función principal que genera imágenes con FLUX.1-dev
 */
async function generarImagenesConFLUX(): Promise<void> {
  // Verificar que la API key está configurada
  if (!process.env.NVIDIA_API_KEY) {
    console.error('Error: No se encontró NVIDIA_API_KEY en las variables de entorno.');
    console.error('Crea un archivo .env con NVIDIA_API_KEY=tu_api_key_aquí');
    return;
  }
  
  // Crear cliente de Nvidia
  const nvidia = new Nvidia({
    apiKey: process.env.NVIDIA_API_KEY,
    timeout: 120000 // 2 minutos (los modelos de generación de imágenes pueden tardar)
  });
  
  // Configurar ruta de salida para las imágenes
  const outputDir = path.join(__dirname, 'imagenes-generadas');
  
  // Crear directorio si no existe
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
    console.log(`Directorio creado: ${outputDir}`);
  }
  
  // Parámetros para la generación de imágenes
  const params = {
    prompt: 'Un astronauta flotando en el espacio profundo, con la Tierra visible a lo lejos, estilo fotorrealista, colores vibrantes, iluminación dramática, alta resolución, detallado',
    seed: 42,           // Para reproducibilidad
    num_images: 2,      // Generar 2 imágenes
    width: 1024,        // Ancho en píxeles
    height: 1024,       // Alto en píxeles
    cfg_scale: 8.5,     // Control de adherencia al prompt
    steps: 40           // Más pasos para mayor calidad
  };
  
  console.log('Generando imágenes con FLUX.1-dev...');
  console.log(`Prompt: "${params.prompt}"`);
  
  try {
    // Realizar la solicitud a la API
    const startTime = Date.now();
    
    const response = await nvidia.images.create('FLUX.1-dev', params);
    
    const endTime = Date.now();
    const timeElapsed = (endTime - startTime) / 1000; // en segundos
    
    console.log(`✓ Generación completada en ${timeElapsed.toFixed(2)} segundos`);
    console.log(`Seed utilizada: ${response.seed}`);
    
    // Verificar que hay imágenes en la respuesta
    if (response.images && response.images.length > 0) {
      console.log(`Se generaron ${response.images.length} imágenes`);
      
      // Guardar cada imagen generada
      response.images.forEach((imageBase64, index) => {
        const timestamp = Date.now();
        const fileName = `flux_${params.seed}_${index + 1}_${timestamp}.png`;
        const outputPath = path.join(outputDir, fileName);
        
        saveBase64Image(imageBase64, outputPath);
      });
      
      console.log('Todas las imágenes han sido guardadas correctamente');
      console.log(`Para generar imágenes similares, usa la seed: ${response.seed}`);
    } else {
      console.log('No se encontraron imágenes en la respuesta');
      console.log('Respuesta recibida:', JSON.stringify(response, null, 2));
    }
    
  } catch (error) {
    console.error('Error al generar las imágenes:');
    
    if (error.response) {
      // Error con respuesta de la API
      console.error(`Error de API: ${error.response.status}`);
      console.error('Detalles:', error.response.data);
    } else if (error.request) {
      // Error de red o sin respuesta
      console.error('Error de red o timeout. La solicitud fue enviada pero no se recibió respuesta.');
      console.error('Es posible que el modelo esté sobrecargado o que la API esté experimentando problemas.');
    } else {
      // Otros errores
      console.error(`Error: ${error.message}`);
    }
    
    console.error('Sugerencias:');
    console.error('- Verifica tu API key');
    console.error('- Reduce la complejidad del prompt');
    console.error('- Intenta con un número menor de imágenes');
    console.error('- Aumenta el timeout si las imágenes son de alta calidad');
  }
}

// Ejecutar la función principal
generarImagenesConFLUX().catch(error => {
  console.error('Error no manejado:', error);
  process.exit(1);
});

Para ejecutar este ejemplo:

1. Guarda el código anterior en un archivo llamado generador-flux.ts
2. Asegúrate de tener un archivo .env con tu API key (NVIDIA_API_KEY=tu_api_key_aquí)
3. Instala las dependencias necesarias con npm install nvidia-node dotenv
4. Compila y ejecuta el código:

   npx tsc generador-flux.ts
   node generador-flux.js

Este ejemplo generará dos imágenes basadas en el prompt proporcionado, mostrando información detallada sobre el proceso de generación y guardando los resultados en el directorio imagenes-generadas.

Características del Ejemplo

• Manejo completo de errores: Identifica y muestra mensajes útiles para diferentes tipos de errores.
• Reproducibilidad: Usa una seed específica para permitir regenerar resultados similares.
• Múltiples imágenes: Demuestra cómo generar y guardar varias imágenes en una sola solicitud.
• Ajustes de calidad: Configura parámetros como steps y cfg_scale para controlar la calidad y adherencia al prompt.
• Seguimiento del tiempo: Mide y muestra el tiempo necesario para completar la generación.
• Gestión de archivos: Crea automáticamente el directorio de salida y nombres de archivo únicos.

Variantes y Personalización

Puedes personalizar este ejemplo modificando:

• El prompt para generar diferentes tipos de imágenes
• La seed para obtener resultados diferentes
• El número de imágenes a generar
• Las dimensiones de las imágenes
• Los parámetros de calidad como steps y cfg_scale

En la siguiente sección, veremos un ejemplo similar para la generación de imágenes con Stable Diffusion XL.

Ejemplo 2: Generación de Imágenes con Stable Diffusion XL

Este ejemplo muestra cómo generar imágenes utilizando el modelo Stable Diffusion XL, aprovechando sus características específicas como prompts positivos y negativos, diferentes samplers y estilos predefinidos.

// generador-sdxl.ts
import * as dotenv from 'dotenv';
import * as fs from 'fs';
import * as path from 'path';
import { Nvidia } from 'nvidia-node';

// Cargar variables de entorno desde .env
dotenv.config();

/**
 * Función para guardar una imagen en formato base64 como archivo
 */
function saveBase64Image(base64Data: string, filePath: string): void {
  // Eliminar el prefijo de datos si existe
  const data = base64Data.replace(/^data:image\/\w+;base64,/, '');
  
  // Crear el buffer y guardar el archivo
  const buffer = Buffer.from(data, 'base64');
  fs.writeFileSync(filePath, buffer);
  
  console.log(`Imagen guardada en: ${filePath}`);
}

/**
 * Función principal que genera imágenes con Stable Diffusion XL
 */
async function generarImagenesConSDXL(): Promise<void> {
  // Verificar que la API key está configurada
  if (!process.env.NVIDIA_API_KEY) {
    console.error('Error: No se encontró NVIDIA_API_KEY en las variables de entorno.');
    console.error('Crea un archivo .env con NVIDIA_API_KEY=tu_api_key_aquí');
    return;
  }
  
  // Crear cliente de Nvidia
  const nvidia = new Nvidia({
    apiKey: process.env.NVIDIA_API_KEY,
    timeout: 180000 // 3 minutos (SDXL puede tardar más que FLUX)
  });
  
  // Configurar ruta de salida para las imágenes
  const outputDir = path.join(__dirname, 'imagenes-sdxl');
  
  // Crear directorio si no existe
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
    console.log(`Directorio creado: ${outputDir}`);
  }
  
  // Parámetros para la generación de imágenes con SDXL
  const params = {
    text_prompts: [
      // Prompt positivo con peso 1.0 (por defecto si no se especifica)
      { 
        text: 'Un dragón majestuoso con escamas brillantes volando sobre un castillo medieval, cielo dramático con nubes tormentosas, estilo fantasy art detallado, iluminación mágica, alta calidad', 
        weight: 1.0 
      },
      // Prompt negativo con peso negativo (-1.0) para evitar elementos no deseados
      { 
        text: 'baja calidad, borroso, distorsionado, malformado, deformado, pixelado, amateur, feo', 
        weight: -1.0 
      }
    ],
    sampler: 'K_DPM_2_ANCESTRAL', // Algoritmo de muestreo
    steps: 50,                  // Número de pasos
    seed: 12345,                // Semilla para reproducibilidad
    width: 1024,                // Ancho en píxeles
    height: 768,                // Alto en píxeles
    cfg_scale: 9.0,             // Control de adherencia al prompt
    samples: 1,                 // Número de imágenes a generar
    style_preset: 'fantasy-art' // Preset de estilo (opcional)
  };
  
  console.log('Generando imagen con Stable Diffusion XL...');
  console.log(`Prompt positivo: "${params.text_prompts[0].text}"`);
  console.log(`Prompt negativo: "${params.text_prompts[1].text}"`);
  console.log(`Estilo: ${params.style_preset}`);
  
  try {
    // Realizar la solicitud a la API
    const startTime = Date.now();
    
    const response = await nvidia.images.create('stabilityai/stable-diffusion-xl', params);
    
    const endTime = Date.now();
    const timeElapsed = (endTime - startTime) / 1000; // en segundos
    
    console.log(`✓ Generación completada en ${timeElapsed.toFixed(2)} segundos`);
    
    // Verificar la estructura de respuesta y extraer imágenes
    let imagesGenerated = false;
    
    // Método 1: A través del campo artifacts (estructura típica de SDXL)
    if (response.artifacts && response.artifacts.length > 0) {
      console.log(`Se generaron ${response.artifacts.length} imágenes (vía artifacts)`);
      
      // Guardar cada imagen generada
      response.artifacts.forEach((artifact, index) => {
        if (artifact.base64) {
          const timestamp = Date.now();
          const fileName = `sdxl_${params.seed}_${index + 1}_${timestamp}.png`;
          const outputPath = path.join(outputDir, fileName);
          
          saveBase64Image(artifact.base64, outputPath);
          imagesGenerated = true;
        }
      });
    }
    // Método 2: A través del campo images (estructura alternativa)
    else if (response.images && response.images.length > 0) {
      console.log(`Se generaron ${response.images.length} imágenes (vía images)`);
      
      // Guardar cada imagen generada
      response.images.forEach((imageBase64, index) => {
        const timestamp = Date.now();
        const fileName = `sdxl_${params.seed}_${index + 1}_${timestamp}.png`;
        const outputPath = path.join(outputDir, fileName);
        
        saveBase64Image(imageBase64, outputPath);
        imagesGenerated = true;
      });
    }
    // Método 3: A través del campo image_base64 (estructura alternativa)
    else if (response.image_base64) {
      console.log('Se generó 1 imagen (vía image_base64)');
      
      const timestamp = Date.now();
      const fileName = `sdxl_${params.seed}_1_${timestamp}.png`;
      const outputPath = path.join(outputDir, fileName);
      
      saveBase64Image(response.image_base64, outputPath);
      imagesGenerated = true;
    }
    
    if (imagesGenerated) {
      console.log('Todas las imágenes han sido guardadas correctamente');
      console.log(`Para generar imágenes similares, usa la seed: ${params.seed}`);
    } else {
      console.log('No se encontraron imágenes en la respuesta');
      console.log('Estructura de respuesta recibida:', JSON.stringify(response, null, 2));
    }
    
  } catch (error) {
    console.error('Error al generar la imagen:');
    
    if (error.response) {
      // Error con respuesta de la API
      console.error(`Error de API: ${error.response.status}`);
      console.error('Detalles:', error.response.data);
    } else if (error.request) {
      // Error de red o sin respuesta
      console.error('Error de red o timeout. La solicitud fue enviada pero no se recibió respuesta.');
      console.error('Es posible que el modelo esté sobrecargado o que la API esté experimentando problemas.');
    } else {
      // Otros errores
      console.error(`Error: ${error.message}`);
    }
    
    console.error('Sugerencias para Stable Diffusion XL:');
    console.error('- Verifica tu API key');
    console.error('- Reduce la longitud o complejidad del prompt');
    console.error('- Prueba con un prompt más simple');
    console.error('- Aumenta el timeout (SDXL puede tardar más que otros modelos)');
    console.error('- Verifica que los valores de los parámetros sean válidos');
  }
}

// Ejecutar la función principal
generarImagenesConSDXL().catch(error => {
  console.error('Error no manejado:', error);
  process.exit(1);
});

Para ejecutar este ejemplo:

1. Guarda el código anterior en un archivo llamado generador-sdxl.ts
2. Asegúrate de tener un archivo .env con tu API key (NVIDIA_API_KEY=tu_api_key_aquí)
3. Instala las dependencias necesarias con npm install nvidia-node dotenv
4. Compila y ejecuta el código:

   npx tsc generador-sdxl.ts
   node generador-sdxl.js

Este ejemplo generará una imagen de alta calidad de un dragón en estilo fantasy-art, utilizando tanto prompts positivos como negativos para controlar el resultado.

Características de Stable Diffusion XL

El ejemplo anterior aprovecha varias características específicas de Stable Diffusion XL:

• Sistema de prompts con pesos: Permite especificar tanto lo que quieres (peso positivo) como lo que no quieres (peso negativo) en la imagen.
• Samplers avanzados: Diferentes algoritmos de muestreo que afectan el estilo y calidad de la imagen.
• Style presets: Estilos predefinidos que ayudan a dirigir la estética de la imagen generada.
• Detección flexible de la respuesta: Maneja múltiples estructuras de respuesta posibles, ya que la API de Nvidia puede devolver las imágenes en diferentes campos dependiendo de la versión.

Comparación con FLUX

Stable Diffusion XL y FLUX tienen diferentes fortalezas:

• FLUX destaca en fotorrealismo y detalles precisos, ideal para escenas realistas, retratos y paisajes naturales.
• Stable Diffusion XL brilla en versatilidad artística, ilustraciones de fantasía y estilos creativos diversos.

La elección entre ambos modelos dependerá del tipo de contenido que deseas generar y el estilo visual que buscas.

Recurso Chat

El recurso Chat es un componente clave de la librería nvidia-node que te permite interactuar con los modelos de lenguaje conversacional de Nvidia. Con este recurso, puedes crear aplicaciones de inteligencia artificial conversacional, asistentes virtuales, sistemas de respuesta a preguntas y muchas otras soluciones basadas en texto.

Propósito y Acceso

Propósito

El recurso Chat está diseñado para facilitar la comunicación con modelos de lenguaje avanzados de Nvidia. Su principal propósito es permitir:

• Generación de texto conversacional basado en instrucciones o preguntas
• Creación de diálogos interactivos con múltiples turnos
• Procesamiento de solicitudes de información, análisis o creación de contenido
• Implementación de asistentes virtuales con capacidad de mantener contexto

A diferencia de los recursos para generación de imágenes o vídeos, el recurso Chat se centra exclusivamente en la generación de texto estructurado como una conversación.

Acceso

Para acceder al recurso Chat, primero debes crear una instancia del cliente Nvidia como se explicó en secciones anteriores. Luego, puedes acceder al recurso a través de la propiedad chat:

import { Nvidia } from 'nvidia-node';

// Crear instancia del cliente Nvidia
const nvidia = new Nvidia();

// Acceder al recurso Chat
const chatResource = nvidia.chat;

// También puedes acceder directamente a completions
const completionsResource = nvidia.chat.completions;

El recurso Chat está estructurado siguiendo un patrón similar al de OpenAI, con un subnivel completions que contiene el método create() para interactuar con los modelos conversacionales.

Método chat.completions.create()

El método principal para interactuar con los modelos de chat es chat.completions.create(). Este método envía una solicitud a la API de Nvidia con los mensajes de la conversación y otros parámetros, y recibe una respuesta generada por el modelo.

Firma del