Interface GenerateImageOptions

Options for a generateImage call.

interface GenerateImageOptions {
    provider?: string;
    model?: string;
    prompt: string;
    modalities?: ImageModality[];
    n?: number;
    size?: string;
    aspectRatio?: string;
    quality?: string;
    background?: ImageBackground;
    outputFormat?: ImageOutputFormat;
    outputCompression?: number;
    responseFormat?: ImageResponseFormat;
    apiKey?: string;
    baseUrl?: string;
    userId?: string;
    seed?: number;
    negativePrompt?: string;
    providerOptions?: Record<string, unknown> | ImageProviderOptionBag;
    providerPreferences?: MediaProviderPreference;
    policyTier?: "safe" | "standard" | "mature" | "private-adult";
    capabilities?: string[];
    usageLedger?: AgentOSUsageLedgerOptions;
    referenceImageUrl?: string;
    faceEmbedding?: number[];
    consistencyMode?: "balanced" | "strict" | "loose";
}

Properties

provider? model? prompt modalities? n? size? aspectRatio? quality? background? outputFormat? outputCompression? responseFormat? apiKey? baseUrl? userId? seed? negativePrompt? providerOptions? providerPreferences? policyTier? capabilities? usageLedger? referenceImageUrl? faceEmbedding? consistencyMode?

Properties

Optional provider

provider?: string

Provider name. When supplied without model, the default image model for the provider is resolved automatically from the built-in defaults registry.

Example

`"openai"`, `"stability"`, `"replicate"`

Optional model

model?: string

Model identifier. Prefer the plain model name with provider set; the combined "provider:model" string is also accepted.

Example

`"gpt-image-2.5-flare"` (with `provider: 'openai'`), `"stable-diffusion-xl-1024-v1-0"`

Either `provider` or `model` (or an API key env var for auto-detection) is required.

prompt

prompt: string

Text description of the desired image.

Optional modalities

modalities?: ImageModality[]

Output modalities requested from the provider (provider-dependent).

Optional n

n?: number

Number of images to generate. Defaults to 1 for most providers.

Optional size

size?: string

Pixel dimensions string, e.g. "1024x1024". Provider-dependent.

Optional aspectRatio

aspectRatio?: string

Aspect ratio string, e.g. "16:9". Used by some providers instead of size.

Optional quality

quality?: string

Quality hint forwarded to the provider. OpenAI's GPT Image models take low, medium, high and auto; DALL·E 3's standard and hd are sent to them as medium and high.

Optional background

background?: ImageBackground

Background style for transparent-capable providers.

Optional outputFormat

outputFormat?: ImageOutputFormat

Desired output file format (e.g. "png", "jpeg", "webp").

Optional outputCompression

outputCompression?: number

Compression level (0–100) for lossy output formats.

Optional responseFormat

responseFormat?: ImageResponseFormat

Whether the provider should return a URL or base64-encoded data.

Optional apiKey

apiKey?: string

Override the provider API key instead of reading from environment variables. With neither provider nor model, it is refused unless the global default names the provider the call goes to first: it is never sent to a provider detected from the environment.

Optional baseUrl

baseUrl?: string

Override the provider base URL, refused as apiKey is with neither provider nor model. An empty or whitespace-only value is unset: it is not refused, the global default's URL and then the provider's base-URL variable apply as they do with no baseUrl, and with none the call goes to the provider's own endpoint.

Optional userId

userId?: string

Optional user identifier forwarded to the provider for moderation tracking.

Optional seed

seed?: number

Random seed for reproducible generation (provider-dependent support).

Optional negativePrompt

negativePrompt?: string

Negative prompt describing content to avoid (provider-dependent support).

Optional providerOptions

providerOptions?: Record<string, unknown> | ImageProviderOptionBag

Arbitrary provider-specific options not covered by the standard fields.

Optional providerPreferences

providerPreferences?: MediaProviderPreference

Provider preferences for reordering or filtering the fallback chain. When supplied, the available image providers are reordered according to preferred and filtered by blocked before building the chain.

Optional policyTier

policyTier?: "safe" | "standard" | "mature" | "private-adult"

Content policy tier. When mature or private-adult, the image provider chain is reordered to prefer uncensored providers (Replicate, Fal) over censored ones (OpenAI, Stability safe mode) and disable_safety_checker: true is applied automatically to the Replicate request so the community model's own NSFW filter does not veto the prompt.

Optional capabilities

capabilities?: string[]

Required provider capabilities for mature/private-adult routing. When referenceImageUrl is set, 'face-consistency' is added automatically so the catalog prefers an IP-Adapter or Instant-ID model that actually respects the reference. Ignored for safe/standard tiers.

Optional usageLedger

usageLedger?: AgentOSUsageLedgerOptions

Optional durable usage ledger configuration for helper-level accounting.

Optional referenceImageUrl

referenceImageUrl?: string

Reference image URL for character/face consistency. See IImageProvider docs.

Optional faceEmbedding

faceEmbedding?: number[]

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

Optional consistencyMode

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

Character consistency mode: 'strict' | 'balanced' | 'loose'. Default 'balanced'.

Settings

Member Visibility

Theme

On This Page

providermodelpromptmodalitiesnsizeaspectRatioqualitybackgroundoutputFormatoutputCompressionresponseFormatapiKeybaseUrluserIdseednegativePromptproviderOptionsproviderPreferencespolicyTiercapabilitiesusageLedgerreferenceImageUrlfaceEmbeddingconsistencyMode