Skip to main content
Version: 1.11.0-beta

images.character

This method allows you to generate consistent character images using Replicate's Ideogram Character model. It maintains character consistency across different scenes and poses while following your prompts. The method is available on both the ImagineoAIClient (for browser environments) and ServerImagineoAIClient (for Node.js server environments).

The method provides two variants:

  • images.character.json() - For JSON payloads with character reference as URL or base64
  • images.character.formData() - For multipart form data with file uploads

JSON Method: images.character.json(input)​

Parameters​

  • input (CharacterGenerationRequest): An object containing the parameters for character generation.

    Key fields in input:

    • prompt (string, required): Description of the scene or pose for the character
    • character_reference_image (string, optional): Character reference as URL or base64 string
    • character_reference_run_id (string, optional): Run ID to use existing image from database
    • rendering_speed (string, optional): Speed/quality trade-off - "Default", "Turbo", or "Quality" (default: "Default")
    • style_type (string, optional): Art style - "Auto", "Fiction", or "Realistic" (default: "Auto")
    • magic_prompt_option (string, optional): Prompt enhancement - "On", "Off", or "Auto" (default: "Auto")
    • aspect_ratio (string, optional): Output aspect ratio - "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", or "2:3" (default: "1:1")
    • resolution (string, optional): Output resolution - "auto", "720", "1024", "1280", or "2048" (default: "auto")
    • seed (number, optional): Seed for reproducible results
    • image (string, optional): Optional background/context image URL or base64
    • mask (string, optional): Optional mask for inpainting specific areas

Returns​

  • Promise<CharacterGenerationResponse>: A Promise that resolves to an object containing details about the initiated character generation run.

    Key fields in response:

    • success (boolean): Whether the request was successful
    • message (string): Status message
    • data (object):
      • run_id (string): Unique identifier for this generation run
      • status (string): Current status of the run
      • live_status (string): Detailed status information
      • progress (number): Progress percentage (0-100)
      • image_url (string): URL of the generated image (when completed)
      • run_type (string): Will be "character-generation"

Example Usage​

import { ImagineoAIClient } from "@imagineoai/javascript-sdk";

const client = new ImagineoAIClient("YOUR_API_KEY", {
  apiKey: "YOUR_API_KEY"
});

// Using JSON with URL reference
const response = await client.images.character.json({
  prompt: "A brave warrior standing in a mystical forest, holding a glowing sword",
  character_reference_image: "https://example.com/character-reference.jpg",
  rendering_speed: "Quality",
  style_type: "Realistic",
  aspect_ratio: "16:9",
  resolution: "2048",
  seed: 12345
});

console.log("Character generation started:", response.data.run_id);

// Using JSON with base64 image
const base64Image = "data:image/jpeg;base64,/9j/4AAQSkZJRg..."; // Your base64 image
const response2 = await client.images.character.json({
  prompt: "The same character now sitting by a campfire at night",
  character_reference_image: base64Image,
  style_type: "Fiction",
  magic_prompt_option: "On"
});

// Using existing run ID as reference
const response3 = await client.images.character.json({
  prompt: "The character in battle armor",
  character_reference_run_id: "previous-run-uuid-here",
  rendering_speed: "Turbo"
});

FormData Method: images.character.formData(input)​

Parameters​

  • input (CharacterGenerationFormDataRequest): An object containing the parameters for character generation with file upload support.

    Key fields (same as JSON method, except):

    • character_reference_file (File | Buffer, optional): Character reference as file upload
      • In browser: File object
      • In Node.js: Buffer object

Example Usage​

// Browser example with file upload
const fileInput = document.getElementById('file-input') as HTMLInputElement;
const file = fileInput.files[0];

const response = await client.images.character.formData({
  prompt: "A wizard casting a powerful spell",
  character_reference_file: file,
  style_type: "Fiction",
  aspect_ratio: "1:1"
});

// Node.js example with Buffer
import fs from 'fs';

const imageBuffer = fs.readFileSync('./character-reference.jpg');

const response = await client.images.character.formData({
  prompt: "The character exploring an ancient temple",
  character_reference_file: imageBuffer,
  rendering_speed: "Quality",
  resolution: "2048"
});

Use Cases​

  1. Game Character Design: Create consistent character art across different scenes and environments
  2. Story Illustration: Maintain character consistency throughout visual storytelling
  3. Marketing Materials: Generate consistent brand mascots in various situations
  4. Animation Pre-production: Create character references for animation projects
  5. Comic Book Creation: Generate consistent character appearances across panels

Best Practices​

  1. High-Quality References: Use clear, well-lit character reference images for best results
  2. Detailed Prompts: Provide specific descriptions of the desired scene while the character appearance is maintained automatically
  3. Style Consistency: Choose a style_type that matches your project's aesthetic
  4. Resolution Selection: Use higher resolutions for final artwork, lower for drafts
  5. Seed Usage: Use the same seed for variations of similar scenes to maintain consistency

Tracking Progress​

After initiating a character generation, you can track its progress using the run_id:

// Monitor progress via WebSocket (if configured)
// The run_type will be "character-generation" for filtering events
// You can check user runs to see the status of your generations

Error Handling​

try {
  const response = await client.images.character.json({
    prompt: "A hero in action",
    character_reference_image: "https://example.com/character.jpg"
  });
  console.log("Success:", response);
} catch (error) {
  if (error.message.includes("422")) {
    console.error("Invalid parameters provided");
  } else if (error.message.includes("401")) {
    console.error("Authentication failed");
  } else {
    console.error("Generation failed:", error.message);
  }
}