Ideogram

This document provides a comprehensive guide for developers on integrating and utilizing Ideogram's image generation capabilities within the AIGNE Framework. The @aigne/ideogram package provides a seamless interface to Ideogram's API, enabling the generation of high-quality images from textual prompts.

This guide will cover the necessary steps for installation, configuration, and usage, complete with code examples and detailed parameter descriptions. For information on other models, refer to the Models Overview.

Installation#

To begin, install the @aigne/ideogram package into your project. You can use your preferred package manager.

npm install @aigne/ideogram

yarn add @aigne/ideogram

pnpm add @aigne/ideogram

Configuration#

Proper configuration is essential for connecting to the Ideogram API. This involves setting up your API key and instantiating the IdeogramImageModel.

API Key Setup#

The model requires an Ideogram API key for authentication. The recommended and most secure method is to set an environment variable.

export IDEOGRAM_API_KEY="your-ideogram-api-key"

Alternatively, you can pass the apiKey directly during the model's instantiation, though this is less secure for production environments.

Model Instantiation#

Once the API key is configured, you can import and create an instance of IdeogramImageModel.

import { IdeogramImageModel } from "@aigne/ideogram";

// The API key will be automatically detected from environment variables.
const model = new IdeogramImageModel();

// Alternatively, provide the API key directly.
const modelWithApiKey = new IdeogramImageModel({
  apiKey: "your-ideogram-api-key", 
});

Basic Usage#

To generate an image, use the invoke method. This method takes an object containing the prompt and any other desired parameters. The only required parameter is prompt.

import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel();

async function generateImage() {
  try {
    const result = await model.invoke({
      model: "ideogram-v3",
      prompt: "A serene mountain landscape at sunset with golden light",
    });
    
    console.log(JSON.stringify(result, null, 2));
  } catch (error) {
    console.error("Error generating image:", error);
  }
}

generateImage();

Response Object#

The invoke method returns a promise that resolves to an object containing the generated images and usage metadata.

{
  "images": [
    {
      "type": "url",
      "url": "https://api.ideogram.ai/generation/...",
      "mimeType": "image/png"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 0
  },
  "model": "ideogram-v3"
}

Input Parameters#

The invoke method accepts several parameters to customize the image generation process.

Advanced Usage#

For more control over the output, you can combine multiple optional parameters in a single invoke call.

import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel();

async function generateAdvancedImage() {
  try {
    const result = await model.invoke({
      prompt: "A futuristic cityscape with neon lights and flying cars",
      model: "ideogram-v3",
      n: 4,
      resolution: "1792x1024",
      renderingSpeed: "TURBO",
      styleType: "FICTION",
      negativePrompt: "blurry, low quality, distorted",
      seed: 12345,
    });
    
    console.log(`Generated ${result.images.length} images.`);
    result.images.forEach((image, index) => {
      console.log(`Image ${index + 1}: ${image.url}`);
    });
  } catch (error) {
    console.error("Error generating image:", error);
  }
}

Default Model Options#

You can set default parameters during the model's instantiation using the modelOptions property. These options will be applied to every invoke call unless overridden by parameters in the call itself.

import { IdeogramImageModel } from "@aigne/ideogram";

const model = new IdeogramImageModel({
  modelOptions: {
    styleType: "REALISTIC",
    renderingSpeed: "QUALITY",
    magicPrompt: "ON",
  },
});

async function generateWithDefaults() {
  // This call will use the default options defined above.
  const result = await model.invoke({
    prompt: "A photorealistic portrait of an astronaut on Mars",
  });
  
  console.log(result);
}

generateWithDefaults();

Summary#

The @aigne/ideogram package offers a direct and efficient way to integrate Ideogram's image generation into your applications. By following the configuration steps and utilizing the provided parameters, you can generate high-quality images tailored to your specific needs.

For a complete and detailed list of all parameters, supported values, and advanced features, please refer to the official Ideogram API Reference.