Skip to main content

Interface: GenerateImageOptions

Defined in: packages/agentos/src/api/generateImage.ts:217

Options for a generateImage call.

Properties​

apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/api/generateImage.ts:263

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.


aspectRatio?​

optional aspectRatio: string

Defined in: packages/agentos/src/api/generateImage.ts:243

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


background?​

optional background: ImageBackground

Defined in: packages/agentos/src/api/generateImage.ts:251

Background style for transparent-capable providers.


baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/generateImage.ts:269

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.


capabilities?​

optional capabilities: string[]

Defined in: packages/agentos/src/api/generateImage.ts:300

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.


consistencyMode?​

optional consistencyMode: "balanced" | "strict" | "loose"

Defined in: packages/agentos/src/api/generateImage.ts:308

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


faceEmbedding?​

optional faceEmbedding: number[]

Defined in: packages/agentos/src/api/generateImage.ts:306

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


modalities?​

optional modalities: ImageModality[]

Defined in: packages/agentos/src/api/generateImage.ts:237

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


model?​

optional model: string

Defined in: packages/agentos/src/api/generateImage.ts:233

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.

n?​

optional n: number

Defined in: packages/agentos/src/api/generateImage.ts:239

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


negativePrompt?​

optional negativePrompt: string

Defined in: packages/agentos/src/api/generateImage.ts:275

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


outputCompression?​

optional outputCompression: number

Defined in: packages/agentos/src/api/generateImage.ts:255

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


outputFormat?​

optional outputFormat: ImageOutputFormat

Defined in: packages/agentos/src/api/generateImage.ts:253

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


policyTier?​

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

Defined in: packages/agentos/src/api/generateImage.ts:292

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.


prompt​

prompt: string

Defined in: packages/agentos/src/api/generateImage.ts:235

Text description of the desired image.


provider?​

optional provider: string

Defined in: packages/agentos/src/api/generateImage.ts:224

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"`

providerOptions?​

optional providerOptions: Record<string, unknown> | ImageProviderOptionBag

Defined in: packages/agentos/src/api/generateImage.ts:277

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


providerPreferences?​

optional providerPreferences: MediaProviderPreference

Defined in: packages/agentos/src/api/generateImage.ts:283

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.


quality?​

optional quality: string

Defined in: packages/agentos/src/api/generateImage.ts:249

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.


referenceImageUrl?​

optional referenceImageUrl: string

Defined in: packages/agentos/src/api/generateImage.ts:304

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


responseFormat?​

optional responseFormat: ImageResponseFormat

Defined in: packages/agentos/src/api/generateImage.ts:257

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


seed?​

optional seed: number

Defined in: packages/agentos/src/api/generateImage.ts:273

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


size?​

optional size: string

Defined in: packages/agentos/src/api/generateImage.ts:241

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


usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/generateImage.ts:302

Optional durable usage ledger configuration for helper-level accounting.


userId?​

optional userId: string

Defined in: packages/agentos/src/api/generateImage.ts:271

Optional user identifier forwarded to the provider for moderation tracking.