Skip to main content
Version: 1.11.0-beta

Reference Image Generation

Generate images using multiple reference inputs with the Runway Gen4 Image Turbo model. This method allows you to create images that incorporate elements from up to 3 reference images, each tagged with a placeholder in your prompt.

Overview​

The reference image generation feature uses Runway's Gen4 Image Turbo model to create images based on a text prompt and multiple reference images. You can tag specific elements in your prompt (like @person, @object) and associate them with reference images.

Method Signature​

// JSON method
client.images.reference.json(input: ReferenceGenerationRequest): Promise<ReferenceGenerationResponse>

// FormData method
client.images.reference.formData(input: ReferenceGenerationFormDataRequest): Promise<ReferenceGenerationResponse>

Input Parameters​

ReferenceGenerationRequest​

ParameterTypeRequiredDescription
promptstringYesText prompt with tagged placeholders (e.g., "@person1", "@object")
imagesReferenceImage[]YesArray of reference images (1-3 images)
aspect_ratiostringNoAspect ratio: "16:9", "9:16", "4:3", "3:4", "1:1", "21:9" (default: "1:1")
resolutionstringNoResolution: "720p" or "1080p" (default: "1080p")

ReferenceImage Object​

ParameterTypeRequiredDescription
image_referencestringYesImage reference - can be a URL, base64 string, or run ID
tagstringYesTag name to use in the prompt (without @ symbol)

Usage Examples​

Basic Example with URLs​

import { ImagineoAIClient } from '@imagineoai/javascript';

const client = new ImagineoAIClient('https://api.imagineoai.com', {
  apiKey: 'your-api-key'
});

const result = await client.images.reference.json({
  prompt: "A person @person1 holding @object in a modern office",
  images: [
    { 
      image_reference: "https://example.com/person.jpg", 
      tag: "person1" 
    },
    { 
      image_reference: "https://example.com/laptop.jpg", 
      tag: "object" 
    }
  ],
  aspect_ratio: "16:9",
  resolution: "1080p"
});

console.log('Generated image:', result.data.image_url);

Using Run IDs from Previous Generations​

// Use images from previous generations
const result = await client.images.reference.json({
  prompt: "Combine @character in the style of @background",
  images: [
    { 
      image_reference: "68703171-6452-40f5-ab14-3fdb718cc471", // Previous run ID
      tag: "character" 
    },
    { 
      image_reference: "5df491d5-9284-4df8-af86-77ed77b10165", // Previous run ID
      tag: "background" 
    }
  ]
});

Multiple Reference Images (Up to 3)​

const result = await client.images.reference.json({
  prompt: "@person1 and @person2 driving @car on a sunny day",
  images: [
    { 
      image_reference: "https://example.com/driver.jpg", 
      tag: "person1" 
    },
    { 
      image_reference: "https://example.com/passenger.jpg", 
      tag: "person2" 
    },
    { 
      image_reference: "https://example.com/sports-car.jpg", 
      tag: "car" 
    }
  ],
  aspect_ratio: "21:9", // Cinematic wide format
  resolution: "1080p"
});

Using FormData (Browser)​

// For form submissions in the browser
const formData = {
  prompt: "A portrait of @person wearing @outfit",
  images: JSON.stringify([
    { 
      image_reference: "base64_encoded_image_data_here", 
      tag: "person" 
    },
    { 
      image_reference: "https://example.com/outfit.jpg", 
      tag: "outfit" 
    }
  ]),
  aspect_ratio: "3:4", // Portrait orientation
  resolution: "1080p"
};

const result = await client.images.reference.formData(formData);

Response Structure​

interface ReferenceGenerationResponse {
  success: boolean;
  message: string;
  data: {
    run_id: string;           // Unique identifier for this generation
    status?: string;          // Current status of the generation
    live_status?: string;     // Real-time status updates
    progress?: number;        // Progress percentage (0-1)
    image_url?: string | null; // URL of generated image when complete
    created_at?: string;      // ISO timestamp of creation
    updated_at?: string;      // ISO timestamp of last update
    run_type?: "reference-generation";
  };
  code?: string;             // Error code if applicable
  details?: any;             // Additional details
}

Important Notes​

Tag Usage​

  • Tags in the prompt must be prefixed with @ (e.g., @person, @object)
  • Tag names in the images array should NOT include the @ symbol
  • The order of images must match the order of their corresponding tags

Image Formats​

  • URLs: Direct image URLs that are publicly accessible
  • Base64: Base64-encoded image data (include data URI prefix)
  • Run IDs: UUIDs from previous generation runs stored in the system

Limitations​

  • Maximum of 3 reference images per request
  • Supported aspect ratios: 16:9, 9:16, 4:3, 3:4, 1:1, 21:9
  • Supported resolutions: 720p, 1080p
  • The model processes images asynchronously - use webhooks or polling to track completion

Best Practices​

  1. Descriptive Tags: Use clear, descriptive tag names that match their role in the prompt

    // Good
    { tag: "main_character", ... }
    { tag: "background_scene", ... }

    // Less clear
    { tag: "img1", ... }
    { tag: "thing", ... }

  2. Consistent Ordering: Always ensure the order of images matches the logical flow of your prompt

  3. Aspect Ratio Selection: Choose aspect ratios that match your intended use:

    • 1:1 - Social media posts, profile pictures
    • 16:9 - Landscape, presentations, videos
    • 9:16 - Portrait, mobile screens, stories
    • 21:9 - Cinematic, ultra-wide displays

  4. Resolution: Use 1080p for high-quality outputs, 720p for faster generation or when quality is less critical

Error Handling​

try {
  const result = await client.images.reference.json({
    prompt: "Generate image with @ref1",
    images: [{ image_reference: "invalid_id", tag: "ref1" }]
  });
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('Reference image not found');
  } else if (error.message.includes('must match')) {
    console.error('Number of tags must match number of images');
  } else {
    console.error('Generation failed:', error.message);
  }
}