Images

1 action. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

images.generate

POST · mutating

Generate an image from a text prompt using the configured image-gen model. Saves the result as a workspace file and returns its URL — render it inline in the chat to show the user.

When the agent calls it: Use this when the user asks for an image / picture / illustration. Pass a clear prompt — the model improves with concrete subjects, style words, and composition hints. After the call, mention the image briefly so the user knows it landed in the conversation. Defaults to the workspace's configured image model (set on /models → Settings → "Default model per task"). To use a specific model for one call, pass modelId (e.g. "bfl/flux-2-pro", "bytedance/seedream-4.5", "openai/gpt-image-1") — call models.list for available image models. Set background:"transparent" or print:true for apparel/sticker art.

• AI tool: images_generate
• API: POST /api/invoke/images.generate

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "modelId": {
      "type": "string"
    },
    "size": {
      "type": "string"
    },
    "aspectRatio": {
      "type": "string"
    },
    "background": {
      "type": "string",
      "enum": [
        "auto",
        "transparent",
        "opaque"
      ]
    },
    "print": {
      "type": "boolean"
    },
    "n": {
      "default": 1,
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    }
  },
  "required": [
    "prompt"
  ]
}