Interface EditImageOptions

Options for an editImage call.

Example

const result = await editImage({
  provider: 'openai',
  image: 'data:image/png;base64,...',
  prompt: 'Add a rainbow in the sky.',
  mode: 'img2img',
  strength: 0.6,
});
interface EditImageOptions {
    provider?: string;
    model?: string;
    image: string | Buffer<ArrayBufferLike>;
    prompt: string;
    mask?: string | Buffer<ArrayBufferLike>;
    mode?: ImageEditMode;
    strength?: number;
    negativePrompt?: string;
    size?: string;
    seed?: number;
    n?: number;
    apiKey?: string;
    baseUrl?: string;
    providerOptions?: Record<string, unknown> | ImageProviderOptionBag;
    usageLedger?: AgentOSUsageLedgerOptions;
    policyTier?: "safe" | "standard" | "mature" | "private-adult";
    capabilities?: string[];
}

Properties

provider? model? image prompt mask? mode? strength? negativePrompt? size? seed? n? apiKey? baseUrl? providerOptions? usageLedger? policyTier? capabilities?

Properties

Optional provider

provider?: string

Provider name (e.g. "openai", "stability", "stable-diffusion-local"). When omitted, auto-detection via env vars is attempted.

Optional model

model?: string

Model identifier. Prefer the plain model name with provider set; the combined "provider:model" string is also accepted. When omitted, the provider's own edit default applies, not its text-to-image default: OpenAI gpt-image-2.5-sunburst, Stability sd3.5-medium, Replicate stability-ai/sdxl (or black-forest-labs/flux-fill-pro with a mask).

Example

`"gpt-image-2.5-sunburst"` (with `provider: 'openai'`), `"sd3.5-medium"`

image

image: string | Buffer<ArrayBufferLike>

Source image as a base64 data URL, raw base64 string, Buffer, local file path, or HTTP/HTTPS URL.

prompt

prompt: string

Text prompt describing the desired changes.

Optional mask

mask?: string | Buffer<ArrayBufferLike>

Optional mask for inpainting. White pixels mark regions to be edited; black pixels mark regions to keep. Accepts the same formats as image.

Optional mode

mode?: ImageEditMode

Edit mode.

  • 'img2img' (default) — prompt-guided transformation.
  • 'inpaint' — mask-guided regional editing.
  • 'outpaint' — extend image borders.

Optional strength

strength?: number

How much to deviate from the source image. 0 = identical, 1 = completely new. Default 0.75.

Optional negativePrompt

negativePrompt?: string

Negative prompt describing content to avoid.

Optional size

size?: string

Output size (e.g. "1024x1024").

Optional seed

seed?: number

Seed for reproducibility (provider-dependent support).

Optional n

n?: number

Number of output images.

Optional apiKey

apiKey?: string

Override the provider API key instead of reading from env vars. Refused when no provider is named (by provider, a model such as 'openai:gpt-image-2.5-sunburst' or the global default), and when the model's provider: prefix names another provider than provider: it is never sent to a provider the call did not name for it.

Optional baseUrl

baseUrl?: string

Override the provider base URL, refused where apiKey is. 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 edit goes to the provider's own endpoint.

Optional providerOptions

providerOptions?: Record<string, unknown> | ImageProviderOptionBag

Arbitrary provider-specific options.

Optional usageLedger

usageLedger?: AgentOSUsageLedgerOptions

Optional usage ledger configuration.

Optional policyTier

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

Content policy tier. When 'mature' or 'private-adult', the edit is rerouted through PolicyAwareImageRouter to pick an uncensored community model (e.g. IP-Adapter FaceID SDXL for face-consistent edits, SDXL for generic img2img) and disable_safety_checker: true is applied automatically to the Replicate request so the model's own NSFW filter does not veto the prompt.

'safe' and 'standard' tiers fall back to whatever provider / model the caller supplied (or env-detected defaults), keeping the existing censored path intact.

Optional capabilities

capabilities?: string[]

Required provider capabilities for mature/private-adult routing. Drives UncensoredModelCatalog filtering (the catalog interface is exported from @framers/agentos/core/llm/routing/UncensoredModelCatalog), so callers can ask for 'face-consistency' when editing a character's outfit, or 'img2img' when the source is a scene the author wants preserved. Ignored for safe/standard tiers.

Settings

Member Visibility

Theme

On This Page

providermodelimagepromptmaskmodestrengthnegativePromptsizeseednapiKeybaseUrlproviderOptionsusageLedgerpolicyTiercapabilities