Interface ImageGenerationRequest

interface ImageGenerationRequest {
    modelId?: string;
    prompt: string;
    modalities?: ImageModality[];
    n?: number;
    size?: string;
    aspectRatio?: string;
    quality?: string;
    background?: ImageBackground;
    outputFormat?: ImageOutputFormat;
    outputCompression?: number;
    responseFormat?: ImageResponseFormat;
    userId?: string;
    seed?: number;
    negativePrompt?: string;
    providerOptions?: Record<string, unknown> | ImageProviderOptionBag;
    referenceImageUrl?: string;
    faceEmbedding?: number[];
    consistencyMode?: "balanced" | "strict" | "loose";
}

Properties

modelId? prompt modalities? n? size? aspectRatio? quality? background? outputFormat? outputCompression? responseFormat? userId? seed? negativePrompt? providerOptions? referenceImageUrl? faceEmbedding? consistencyMode?

Properties

Optional modelId

modelId?: string

prompt

prompt: string

Optional modalities

modalities?: ImageModality[]

Optional n

n?: number

Optional size

size?: string

Optional aspectRatio

aspectRatio?: string

Optional quality

quality?: string

Optional background

background?: ImageBackground

Optional outputFormat

outputFormat?: ImageOutputFormat

Optional outputCompression

outputCompression?: number

Optional responseFormat

responseFormat?: ImageResponseFormat

Optional userId

userId?: string

Optional seed

seed?: number

Optional negativePrompt

negativePrompt?: string

Optional providerOptions

providerOptions?: Record<string, unknown> | ImageProviderOptionBag

Optional referenceImageUrl

referenceImageUrl?: string

Reference image URL or data URI for character/face consistency.

Providers that support identity preservation map this to model-specific inputs:

  • Replicate (Pulid): main_face_image
  • Replicate (Flux Redux): image
  • Fal (IP-Adapter): ip_adapter_image
  • SD-Local: ControlNet with IP-Adapter preprocessor
  • OpenAI/Stability/OpenRouter/BFL: ignored (debug warning logged)

Optional faceEmbedding

faceEmbedding?: number[]

Pre-computed 512-dim face embedding vector for drift detection.

When provided alongside referenceImageUrl, the AvatarPipeline verifies generated face identity via cosine similarity against this anchor vector.

Optional consistencyMode

consistencyMode?: "balanced" | "strict" | "loose"

Character consistency mode controlling identity preservation strength.

  • 'strict' — Maximum preservation. Uses Pulid/InstantID. Face guaranteed consistent but output creativity is constrained.
  • 'balanced' — Moderate preservation. IP-Adapter strength ~0.6. Good for expression variants where some variation is acceptable.
  • 'loose' — Light guidance. Reference influences mood/style but face may drift. Good for "inspired by" generations.

Default

'balanced'

Settings

Member Visibility

Theme

On This Page

modelIdpromptmodalitiesnsizeaspectRatioqualitybackgroundoutputFormatoutputCompressionresponseFormatuserIdseednegativePromptproviderOptionsreferenceImageUrlfaceEmbeddingconsistencyMode