Skip to main content

Interface: GenerateImageOptions

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

Options for a generateImage call.

Properties​

apiKey?​

optional apiKey: string

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

Override the provider API key instead of reading from environment variables.

aspectRatio?​

optional aspectRatio: string

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

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:219

Background style for transparent-capable providers.

baseUrl?​

optional baseUrl: string

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

Override the provider base URL.

capabilities?​

optional capabilities: string[]

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

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:268

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

faceEmbedding?​

optional faceEmbedding: number[]

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

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

modalities?​

optional modalities: ImageModality[]

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

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

model?​

optional model: string

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

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

Example​

`"dall-e-3"` (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:211

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

negativePrompt?​

optional negativePrompt: string

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

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

outputCompression?​

optional outputCompression: number

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

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

outputFormat?​

optional outputFormat: ImageOutputFormat

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

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:252

Content policy tier. When mature or private-adult, the image provider chain is reordered to prefer uncensored providers (Replicate, Fal) over censored ones (DALL-E, 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:207

Text description of the desired image.

provider?​

optional provider: string

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

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:237

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

providerPreferences?​

optional providerPreferences: MediaProviderPreference

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

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:217

Quality hint forwarded to the provider (e.g. "hd" for DALL-E 3).

referenceImageUrl?​

optional referenceImageUrl: string

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

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

responseFormat?​

optional responseFormat: ImageResponseFormat

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

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

seed?​

optional seed: number

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

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

size?​

optional size: string

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

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

usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

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

Optional durable usage ledger configuration for helper-level accounting.

userId?​

optional userId: string

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

Optional user identifier forwarded to the provider for moderation tracking.