Generating Images

Create images from prompts, generate variations, and combine images with text.

The generateImage() function creates images through a session-admitted Rust image binding. Its model argument is a stable deployment alias; the tool server privately chooses the provider, upstream model, endpoint, credential, and defaults behind that alias.

Basic Image Generation

let image = generateImage(
  prompt: "A serene mountain landscape at sunset"
)

"Generated: {{image}}"
"Path: {{image.path}}, type: {{image.mimeType}}, {{image.size}} bytes"

Returns a file object describing the generated image:

{path: string, filename: string, mimeType: string, size: number, url?: string}

Property access is supported (image.path, image.filename, ...). When coerced to a string (e.g. {{image}}), the file object renders as its path; url is populated once the file is published.

With Filename

let portrait = generateImage(
  prompt: "Portrait of a woman in Renaissance style",
  filename: "renaissance-portrait.png"
)

Specify the output filename.

Specifying Model

let logo = generateImage(
  prompt: "Modern tech company logo",
  model: "brand-illustration"
)

Supported binding families:

  • OpenAI Images for text-to-image generation
  • Gemini image models for generation and reference-image editing
  • Vertex Imagen for text-to-image generation
  • Stock/search photos: unsplash, google-images (resolved through admitted image-search and image-acquisition tool bindings)
  • Typesetting: typst (see typst())
  • Scripted Rust image bindings for deterministic offline tests

If model is omitted, Kaya requests the explicitly admitted default image alias. An exact alias such as brand-illustration requires the session capability kaya.image.brand-illustration; Kaya never widens the call to an ungranted provider or silently consults the old kayad image profile. See Configuration.

Image Size

let banner = generateImage(
  prompt: "Wide banner image of a cityscape",
  size: "1536x1024"
)

Size support is binding-specific. Kaya includes the requested dimensions in cache and replay identity; the selected Rust connector translates them to the provider's closest supported size or aspect ratio. Omitting size uses the binding's reviewed default.

Generating Multiple Images

let variations = generateImage(
  prompt: "Abstract art with vibrant colors",
  count: 3,
  filename: "abstract-art"
)

// variations is an array of file objects (file[])
for image in variations {
  "Generated: {{image.filename}}"
}

When count > 1, returns an array of file objects (file[]).

Dynamic Generation in Loops

let name = "Alice"
let styles = ["watercolor", "oil", "sketch", "pixel art"]

for style in styles {
  let image = generateImage(
    prompt: "Portrait of {{name}} in {{style}} style",
    filename: "portrait-{{style}}.png"
  )
  "Generated {{style}} portrait: {{image}}"
}

Complete Example

let character = "wizard"
let setting = "enchanted forest"
let style = "watercolor"

let artwork = generateImage(
  prompt: "A {{character}} in an {{setting}}, {{style}} style, highly detailed",
  model: "book-illustration",
  size: "1024x1024",
  filename: "{{character}}-artwork.png"
)

"Created artwork: {{artwork}}"

Content Generation Pipeline

// 1. Generate text content
let blogPost = generate(
  systemPrompt: "You are a professional tech blogger",
  message: "Write a blog post about {{topic}}",
  model: "gemini-fast"
)

// 2. Generate hero image
let heroImage = generateImage(
  prompt: "Header image for blog post about {{topic}}, modern, professional",
  filename: "blog-hero.png"
)

// 3. Render social media card
let socialCard = generateImage(
  prompt: "Social media card titled {{topic}} with an excerpt of the post",
  filename: "social-card.png"
)

"Blog post ready with hero image and social card"

Multi-Modal Generation

let productName = "Smart Watch Pro"
let features = ["Heart rate monitoring", "GPS tracking", "Waterproof"]

// Generate product description
let description = generate(
  message: "Write a compelling product description for {{productName}} with features: {{features | join: ', '}}",
  model: "openai-fast"
)

// Generate product images
let productImages = generateImage(
  prompt: "{{productName}} product photography, professional, white background",
  count: 3,
  filename: "product-photo"
)

// Create marketing materials
for image in productImages {
  let marketing = generateImage(
    prompt: "Marketing card for {{productName}}: {{description}}",
    filename: "marketing-{{_index}}.png"
  )
  "Created marketing material: {{marketing}}"
}

Iterative Generation with Feedback

let attempt = 0
let maxAttempts = 3
let approved = false

while !approved && attempt < maxAttempts {
  // Bare assignments — `let` inside the loop body would create
  // block-scoped shadows that are discarded each iteration
  attempt = attempt + 1

  let design = generateImage(
    prompt: "Logo design for tech startup, modern, minimalist",
    filename: "logo-v{{attempt}}.png"
  )

  let feedback = generate(
    message: "Evaluate this logo design against brand guidelines. Say 'approved' if it passes: {{design | image}}"
  )

  // feedback is a string; keep the approval test in a named variable
  let isApproved = feedback.includes(value: "approved")
  if isApproved {
    approved = true
    "Design approved after {{attempt}} attempts"
  } else {
    "Attempt {{attempt}} needs revision: {{feedback}}"
  }
}

Batch Processing with Generation

let customers = [
  {name: "Alice", plan: "premium"},
  {name: "Bob", plan: "basic"},
  {name: "Carol", plan: "premium"}
]

for customer in customers {
  let email = generate(
    systemPrompt: "You are a customer success manager",
    message: "Write a personalized email for {{customer.name}} on the {{customer.plan}} plan",
    chat: false
  )

  let emailCard = generateImage(
    prompt: "Email card for {{customer.name}} on the {{customer.plan}} plan",
    filename: "email-{{customer.name}}.png"
  )

  "Created email for {{customer.name}}: {{emailCard}}"
}

Best Practices

  1. Describe thoroughly: More detail = better results
  2. Specify style: Include artistic style, mood, lighting in your prompt
  3. Use appropriate sizes: Match size to use case (social media, print, web)
  4. Generate variations: Create multiple options and pick the best
  5. Iterate: Refine prompts based on results

Testing

For offline tests, bind an alias such as image-fixture to the scripted Rust media provider. It returns deterministic, structurally valid PNGs without network access or credentials. The session still needs a grant for that alias.

Next Steps