Interface: GenerateImageOptions
Defined in: packages/agentos/src/api/generateImage.ts:217
Options for a generateImage call.
Properties
apiKey?
optionalapiKey: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?
optionalaspectRatio: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?
optionalbackground:ImageBackground
Defined in: packages/agentos/src/api/generateImage.ts:251
Background style for transparent-capable providers.
baseUrl?
optionalbaseUrl: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?
optionalcapabilities: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?
optionalconsistencyMode:"balanced"|"strict"|"loose"
Defined in: packages/agentos/src/api/generateImage.ts:308
Character consistency mode: 'strict' | 'balanced' | 'loose'. Default 'balanced'.
faceEmbedding?
optionalfaceEmbedding:number[]
Defined in: packages/agentos/src/api/generateImage.ts:306
Pre-computed 512-dim face embedding for drift detection.
modalities?
optionalmodalities:ImageModality[]
Defined in: packages/agentos/src/api/generateImage.ts:237
Output modalities requested from the provider (provider-dependent).
model?
optionalmodel: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?
optionaln:number
Defined in: packages/agentos/src/api/generateImage.ts:239
Number of images to generate. Defaults to 1 for most providers.
negativePrompt?
optionalnegativePrompt:string
Defined in: packages/agentos/src/api/generateImage.ts:275
Negative prompt describing content to avoid (provider-dependent support).
outputCompression?
optionaloutputCompression:number
Defined in: packages/agentos/src/api/generateImage.ts:255
Compression level (0–100) for lossy output formats.
outputFormat?
optionaloutputFormat:ImageOutputFormat
Defined in: packages/agentos/src/api/generateImage.ts:253
Desired output file format (e.g. "png", "jpeg", "webp").
policyTier?
optionalpolicyTier:"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?
optionalprovider: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?
optionalproviderOptions:Record<string,unknown> |ImageProviderOptionBag
Defined in: packages/agentos/src/api/generateImage.ts:277
Arbitrary provider-specific options not covered by the standard fields.
providerPreferences?
optionalproviderPreferences: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?
optionalquality: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?
optionalreferenceImageUrl:string
Defined in: packages/agentos/src/api/generateImage.ts:304
Reference image URL for character/face consistency. See IImageProvider docs.
responseFormat?
optionalresponseFormat:ImageResponseFormat
Defined in: packages/agentos/src/api/generateImage.ts:257
Whether the provider should return a URL or base64-encoded data.
seed?
optionalseed:number
Defined in: packages/agentos/src/api/generateImage.ts:273
Random seed for reproducible generation (provider-dependent support).
size?
optionalsize:string
Defined in: packages/agentos/src/api/generateImage.ts:241
Pixel dimensions string, e.g. "1024x1024". Provider-dependent.
usageLedger?
optionalusageLedger:AgentOSUsageLedgerOptions
Defined in: packages/agentos/src/api/generateImage.ts:302
Optional durable usage ledger configuration for helper-level accounting.
userId?
optionaluserId:string
Defined in: packages/agentos/src/api/generateImage.ts:271
Optional user identifier forwarded to the provider for moderation tracking.