Skip to main content
Glama

AIGE

by ws.aige
OverviewDiscussionsAdmin

Generate AI Image

antix_generate_image

Generate one or more AI images for a SINGLE prompt. ASYNC — queues the task and returns a taskId in <1s; call antix_check_task ~10–25s later to get the inline preview(s) and URLs.

🚀 IF THE USER WANTS MULTIPLE DIFFERENT PROMPTS (e.g. 'generate 5 different scenes: beach, café, gym, library, sunset'), USE antix_generate_image_batch INSTEAD. That tool submits all N prompts in one call, fal runs them in parallel, total wall time = ~one item's time instead of N × time, credits are charged atomically, and polling is one call against a single batchId. This tool is for ONE prompt only (with optional count: 2-4 variations of that one prompt).

⚠️ ALWAYS pass user's specified parameters explicitly — do NOT use defaults if the user requested specific settings. If the user says 'use GPT model 9:16 ratio with high quality,' you MUST pass model: 'gpt-image-2', aspectRatio: '9:16', AND quality: 'high'. Missing any of these means we silently fall back to defaults and the user's request is ignored.

🖼️ IMG2IMG & CHARACTER CONSISTENCY — read this section carefully.

The server automatically resolves the reference image in this priority order:

  1. Explicit referenceImage arg (URL or base64 data URL) — always wins.

  2. Most recent image in the character's GALLERY (the multi-image reference pool backing the AIGE PromptBar's 'Upload Character Image' dialog). This is the PREFERRED img2img path — users curate references in the gallery and they auto-apply to every future generation without needing to forward image bytes per call. Manage via antix_list_character_gallery + antix_add_to_character_gallery.

  3. Saved avatar of characterId (legacy single-image fallback).

  4. Pure text-to-image if none of the above resolves.

When to pass referenceImage explicitly: • User attached an image AND it's NOT a saved AIGE character (e.g. an inspiration photo, a scene reference, a sketch). • User pasted an HTTPS URL. • User uploaded to https://aige.ws/r and gave you the short URL. • You're in Claude Code with file access — read the file, base64-encode, pass as data:image/...;base64,....

When you have BOTH a chat-attached image AND a characterId, prefer referenceImage (the explicit upload wins) — the user wanted that specific image, not the saved avatar.

If you genuinely can't access the chat-attached bytes (your chat client shows you the image as vision content but doesn't expose it as data URL/URL for tool args): do NOT silently fall back to text-to-image. Reply to the user: 'My chat client isn't forwarding your image bytes in a tool-callable form. Options: (a) paste a public URL of the image, (b) upload to https://aige.ws/r and paste the short link, or (c) if it's a saved AIGE character, tell me their name and I'll use that.' Then wait.

Supported img2img models: nano-banana-lite, nano-banana-2 (best default for character continuation), nano-banana-pro (highest fidelity), gpt-image-2 (auto-routes to /edit), and flux-pro (auto-routes to /redux). Nano Banana and GPT Image accept ordered referenceImages; Flux uses the first reference. Recraft variants are text-only, so choose another model when a reference must be honored.

Characters and reference images COMBINE. Passing characterId alongside referenceImages sends both — the character's own images lead (identity anchors best in the first slot), your references follow. Use characterUse to say what you need from the character: face (default, the identity uploads), body (their gallery shots, for build/framing/wardrobe) or both.

Models — pick by user intent (or use the user's explicit model name). Unsure? Call antix_pick_model (free, instant) with the use case. • nano-banana-lite — 4 cr/img, cheapest + fastest. Drafts, moodboards, bulk exploration; img2img via /edit. Half the price of nano-banana-2 — use it when quantity beats polish. • nano-banana-2 — DEFAULT, 8 cr/img. Fast photoreal; character work, faces, portraits, product shots, character continuation. • nano-banana-pro — 15 cr/img. Gemini 3 Pro image preview. Highest fidelity, complex multi-subject scenes, editorial. • gpt-image-2 — 6 cr/img (medium). OpenAI GPT Image 2. Strongest at text-in-image, posters, magazine covers. Supports quality. • recraft-v4 — 4 cr/img. Recraft V4.1. Vector/illustration/icon work (text-only). • recraft-v4-pro — 25 cr/img. Recraft V4.1 Pro. Premium illustration quality (text-only). • recraft-v4-flash — 1 cr/img. Recraft V4.1 Flash — ultra-fast (1.3s), lowest-cost raster illustration/icon drafts (text-only). • recraft-v4-utility — 4 cr/img. Recraft V4.1 Utility — faster, cost-optimized for high-volume work (text-only). • recraft-v4-utility-pro — 25 cr/img. Recraft V4.1 Utility Pro — faster pro tier for studio pipelines (text-only). • flux-pro — 8 cr/img. Black Forest Labs flux-pro v1.1. Photoreal alternative; supports img2img via /redux.

Per-parameter behavior (so you know what gets honored): • model — always honored. If user names a specific model, pass it verbatim. • aspectRatio — always honored. Allowed values: 1:1, 16:9, 9:16, 4:5, 3:4, 4:3, 3:2, 2:3, 21:9, 9:21. Mapping is automatic per model: nano-banana models receive the raw string; gpt-image-2 / flux-pro / recraft receive fal's preset enum (portrait_16_9 for 9:16/9:21/2:3, landscape_16_9 for 16:9/21:9/3:2, square_hd for 1:1, etc.). Pick the closest match if user says e.g. 'portrait' (use 9:16) or 'landscape' (use 16:9). • resolution — 0.5K / 1K / 2K / 4K. Honored by nano-banana-2 (all four), nano-banana-pro (1K/2K/4K; 0.5K clamps to 1K), and GPT Image 2 (1K/2K/4K via explicit dimensions). Other models render at native resolution. • quality — auto / low / medium / high, honored by GPT Image 2. Default is medium; quality and resolution both affect the canonical credit action. Other models use their native tier. • style — photo / anime / cinematic / neutral. Non-neutral styles are injected into the provider prompt and stored for exact regeneration. • count — 1-4. Total cost = per-image-cost × count. All variants returned inline via check_task. (Note: recraft-v4 / recraft-v4-pro / recraft-v4-flash / recraft-v4-utility / recraft-v4-utility-pro have no native batch support — we fan out parallel fal calls for count > 1.) • characterId — keeps a saved AIGE character's face/style across generations. The server automatically attaches the character's saved avatar as the reference image (img2img), so just passing characterId is enough — no need to also forward the user's chat-attached image when they're working with a saved character. Unique to AIGE.

Returns: taskId, creditsSpent (charged upfront, atomically), perImageCost, creditsRemaining, estimatedSeconds, and nextStep instructions for polling. On INSUFFICIENT_CREDITS, response includes action with the URL to buy more credits. On generation failure (e.g. content_policy_violation), credits are refunded automatically.

Input Schema

NameRequiredDescriptionDefault
countNo
modelNo
styleNo
promptYes
qualityNo
messageIdNoOptional originating chat message id for inline media reconciliation.
projectIdNoAIGE work-project id that should receive pending and completed assets.
sessionIdNoOptional AIGE agent session id within projectId.
resolutionNo
aspectRatioNo
characterIdNo
characterUseNo
idempotencyKeyNoStable client-generated key. Retrying the same request with the same key must not charge or queue twice.
referenceImageNo
referenceImagesNo
referenceImageUrlNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the thin annotations (idempotentHint/destructiveHint false) by disclosing async queueing, return-in-<1s, poll at 10–25s, upfront atomic credit charge with per-image cost math, and automatic refunds on provider failure such as content_policy_violation. One inconsistency is left unresolved at the description level: annotations declare idempotentHint=false while the schema advertises an idempotencyKey that guarantees 'same key must not charge or queue twice' — the description never reconciles these, so retry safety is ambiguous.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the single-vs-batch decision and the async contract, then organized into bolded, skimmable sections — appropriate shape for a 16-parameter tool. It is very long, however, and the model list is partially restated across the img2img and model-selection sections, which is redundant for an agent that reads sequentially.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async, credit-consuming, multi-model generation tool with no output schema, the description covers the full lifecycle: what is returned (taskId, creditsSpent, perImageCost, creditsRemaining, estimatedSeconds, nextStep), how to poll, and what happens on insufficient credits and on generation failure. Nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25%, so the description carries the burden and mostly delivers: per-parameter honor semantics for model, aspectRatio (with provider-specific preset mapping), resolution clamping, quality, style injection, count fan-out and cost multiplication, characterUse, and a 4-step reference-image resolution priority order. Gaps remain for referenceImageUrl (never explained alongside referenceImage/referenceImages) and for how the three reference variants interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb + resource + scope ('Generate one or more AI images for a SINGLE prompt') and immediately names the sibling it is not for — 'IF THE USER WANTS MULTIPLE DIFFERENT PROMPTS ... USE antix_generate_image_batch INSTEAD'. An agent can distinguish this from antix_generate_image_batch, antix_generate_video and antix_enhance_prompt without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: single prompt here, N different prompts to the batch tool, model selection by intent, and a fallback to antix_pick_model when unsure. It also enumerates when to pass referenceImage explicitly vs. let the character gallery/avatar resolve, and tells the agent exactly what to say to the user when chat-attached bytes are unavailable instead of silently degrading to text-to-image.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AIGE toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources