imagegen

This server is the agent door to the local image-generation daemon — the service that produces the platform's visual output: hero images for intelligence articles, covers and section illustrations for knowledge products, and any one-off image an agent needs mid-task. The server itself is a thin front; the daemon holds the queue, the settings, and the generation history.

Its most distinctive tool is imagegen_compose_prompt: instead of generating from a bare title, it has an illustrator agent read the full source article and compose a rich editorial prompt — style, subject, alt text, rationale — before anything renders. That two-step shape (an agent composes, the daemon renders) is the platform's standing division of labor: judgment in the agent, mechanical execution in the daemon, and it produces markedly better images than a template prompt. Batch generation, history, stats, and a health check round out the surface.

How your agents use it

• "Give this article a proper hero image." The agent calls imagegen_compose_prompt — an illustrator agent reads the article and returns a grounded prompt — then imagegen_generate with it. This is exactly what the intelligence pipeline's illustration step does on schedule.
• "Illustrate section 4 of the product." — imagegen_generate_section_image, the products pipeline's dedicated entry point.
• "What have we generated this month?" — imagegen_list_generations and imagegen_stats keep volume and output browsable.

Prerequisites

The image-generation daemon must be running (Dashboard ▸ Platform Health). Rendering runs on your Gemini API key — image generation is a paid, per-image call on your own account, so unattended volume deserves the same deliberateness as any spend. Keys and daemon settings live in the configuration reference.

Tool reference

Tool	Parameters	What it does
imagegen_health	—	Check the imagegen daemon's health. Returns Gemini API reachability, daemon uptime, image_config compatibility flag, daily success count, and daily cap. Call this before imagegen_generate to verify the daemon is reachable — otherwise generation will fail silently.
imagegen_generate	article_path*: string, prompt: string, aspect_ratio: string, resolution: string, style: string, alt_text: string, overwrite_existing: boolean	Generate a single hero image for an intelligence article. The daemon calls Gemini 3.1 Flash Image, writes PNG to content/observer-news/images/{slug}.png, and patches the article's YAML frontmatter (featured_image + featured_image_alt). Breaking content_type is rejected by design. Call imagegen_compose_prompt first for article-grounded prompt quality.
imagegen_generate_section_image	product_folder_path*: string, section_dir*: string, slot*: integer, prompt*: string, style: string, aspect_ratio: string, resolution: string, alt_text: string, overwrite_existing: boolean	Generate ONE per-section image for a Products HUMAN-FACING section. The daemon calls Gemini and writes WebP to products/{slug}/scope/human/{section_dir}/image_{slot}.webp (the daemon computes the path — you never do path math), then returns the project-relative image_path. Does NOT patch frontmatter: your section's _human.md references image_{slot}.webp RELATIVELY (co-located in the same folder). Compose the prompt from the section's actual content. Use slot=1,2,3… for the section's images in order.
imagegen_batch	items*: array	Batch-generate images for up to 10 articles sequentially. Each item has the same schema as imagegen_generate. Returns a results array — each element is either a success response or an error response.
imagegen_compose_prompt	article_path*: string, agent: string, model: string	Have a subagent (default: news-illustrator, sonnet) read the full article and compose a rich editorial hero-image prompt grounded in the article's actual content. Returns {prompt, style, alt_text, rationale?}. Takes 30-90s. Use this before imagegen_generate for much higher prompt quality than the daemon's default title+excerpt template.
imagegen_settings_get	—	Get the daemon's current effective settings (daily_cap, default_aspect_ratio, default_resolution, default_style, reference file caps) + which env vars are overriding persisted values.
imagegen_stats	since: string	Aggregate statistics from the cost ledger. Returns counts (success / safety_block / failure), total cost USD, and breakdowns by resolution and content type. Supports since=ISO8601 filter.
imagegen_list_generations	limit: integer, offset: integer, since: string, status: string	Paginated listing of recent ledger entries (newest-first). Success entries include tokens/cost/duration; failure entries include error/detail. Useful for forensic inspection of recent activity.

Where to go next

• Intelligence — publishing — where hero images land in the article pipeline
• Products — covers and section illustrations in the knowledge-product pipeline
• Daemons — the service behind this server