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

npm install @aigne/ideogram

yarn

yarn add @aigne/ideogram

pnpm

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.

.env

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.

Instantiating the Model

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.

Generating an Image

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.

Example Response

{
  "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.

Advanced Image Generation

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);
  }
}

generateAdvancedImage();

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.

Setting Default Options

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.