Skip to main content
Glama
Sign In

agent-media

by ai.agent-media.api
OverviewDiscussionsAdmin

generate_image

Render one image from YOUR prompt. Without refs it paints from the prompt; with refs (https URLs) it edits/composes from them, a portrait to re-light, a product to place in a hand, a character sheet to pose. Use it to build the reference a video needs (portrait first, then generate_video with that URL in refs). Models: gpt-image-2.6, gpt-image-2.6-flare, gpt-image-2.5, gpt-image-2.5-flare, gpt-image-2, nano-banana-pro, nano-banana-2.1 (default gpt-image-2.5). Spends credits per image (see list_models). Returns a job id, poll get_run_status for the image URL.

When the user wants to provide a product photo, portrait, screenshot, or image reference, check tools/list. If open_upload_panel is available, offer it first: call open_upload_panel with {}, show its inline panel or returned browser link, and wait for the user to finish. Then call get_uploads with the returned session_id and use the exact ready image_url in refs, first_frame, last_frame, or the matching skill image field. Do not start a reference-dependent generation until the required images are ready. The panel accepts still PNG, JPEG, and WebP, up to 10 images and 25 MB each. Images expire 24 hours after the panel is created; show the returned expiry, request a new upload if expired, and never make a permanent copy. Uploading uses no generation credits. Do not ask the user for base64, shell commands, or a public hosting service; do not continuously poll while waiting for them. Only call these tool names when discovered. If they are missing from the connected tool catalog, call upload_image with {} to open the same panel; use the returned panel: upload_key with upload_image to retrieve images after the user finishes. If that reports the panel is unavailable, use upload_image only for an already accessible file or URL. Do not build an upload page or request a local folder as a substitute for the existing panel. Never invent access to a chat attachment: if you cannot read it, explain that and offer the panel when available. Browser fallback works without inline UI support; do not promise an inline panel in every client. Inspect the native image previews returned with retrieved uploads before describing them or writing image-specific prompts. Never infer what the image shows from an email domain, account metadata, or filename. Use the original URLs for generation, not preview bytes. If the session ID was lost, call get_uploads with {} to list recent sessions, or upload_image with {"upload_key":"panel:recent"} for cached catalogs; retrieve the matching session before asking for re-upload. Account-wide recent uploads may belong to other conversations, so clarify ambiguous selection. Uploading stores an image; it does not attach it to a generation automatically. If the user already requested a generation with these images, continue that request using the returned URLs; do not stop at "upload complete" or ask again whether to use them. If make_ugc fits the requested outcome, pass a person photo as image or a product photo as product_image, then call quote_ugc before spending. Otherwise compose the direct generators: for generate_image, put the relevant image_url values in refs; for generate_video, use refs for product/person/appearance references, or first_frame for animating a still (last_frame only for an explicitly requested ending frame), and never combine refs with frame fields. Preserve the user's intended image roles and model limits; ask only if the role or selection is unclear. Include the URL in the tool arguments, not only in the prompt. Do not substitute a newly generated image for the uploaded reference. If the request was upload-only, report readiness and wait for a generation request; uploading alone does not authorize spending credits. After submitting, poll get_run_status and return the result.

IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call upload_image FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.

RETRY SAFETY: set request_id to a fresh UUID for a new generation. Reuse the exact same request_id and inputs only to recover a lost response; that returns the original job without another charge. A deliberately new generation needs a new request_id. Keep the returned job_id and poll get_run_status. Never invent a refund.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>"
    },
    "name": "generate_image"
  }
}

Input Schema

NameRequiredDescriptionDefault
refsNoReference images (https URLs, up to 4). With refs the model EDITS/composes from them (a product into a hand, a portrait re-lit); without, it paints from the prompt alone.
sizeNo1024x1536 portrait (default, for 9:16 video), 1024x1024 square, 1536x1024 landscape.1024x1536
modelNoA live image model id from list_models, or "auto" to let agent-media pick from recent results. Omit for the default (gpt-image-2.5).
promptYesWhat to paint. Be concrete: subject, age, framing, light, lens, mood, what the hands do.
request_idNoUnique request identity (prefer a UUID). Reuse with identical inputs to recover the same job after a lost response; choose a new identity only for an intentionally new generation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / model / description
      Previous value: -"A live image model id from list_models, or \"auto\" to let agent-media pick from recent results. Omit for the default (gpt-image-2.6)."New value: +"A live image model id from list_models, or \"auto\" to let agent-media pick from recent results. Omit for the default (gpt-image-2.5)."
  2. Changed1 schema field changed
    • changedInput schema / properties / model / description
      Previous value: -"A live image model id from list_models, or \"auto\" to let agent-media pick from recent results. Omit for the default (gpt-image-2.5)."New value: +"A live image model id from list_models, or \"auto\" to let agent-media pick from recent results. Omit for the default (gpt-image-2.6)."
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Adds substantial behavior beyond the annotations: it spends credits per image, is async (returns a job id to poll via get_run_status), enforces https URLs and rejects base64 because arguments are echoed to the user, and documents retry semantics where reusing a request_id returns the original job without another charge. The cost amount is deferred to list_models, and the retry-idempotency explanation is buried deep in the text.

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

Conciseness2/5

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

The core definition is two good sentences, but it is followed by several hundred words of upload-panel workflow, session expiry rules, and cross-tool instructions that belong to open_upload_panel or upload_image. The result is a wall of text where the generation-specific retry and cost rules are hard to find.

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

Completeness4/5

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

For a five-parameter generation tool with no output schema, it covers what matters: cost, async job flow, return value (job id and image URL via get_run_status), reference-image constraints, and retry safety. It is arguably over-complete on irrelevant upload mechanics rather than under-complete.

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

Parameters3/5

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

Schema coverage is 100%, so refs, size, and request_id are already documented in structured form, and the description mostly restates them. It adds some value by naming the concrete model ids and noting that the default portrait size is intended for 9:16 video, but that is marginal over the schema's own `description` fields.

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 and resource: 'Render one image from YOUR prompt,' then immediately distinguishes the two modes ('Without refs it paints from the prompt; with refs... it edits/composes from them'). It also names the sibling relationship to generate_video and make_ugc, so an agent can separate this from neighboring generators without opening a schema.

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

Usage Guidelines4/5

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

Gives explicit routing: use make_ugc with quote_ugc when UGC fits, otherwise compose direct generators, use refs for appearance references and first_frame for animating stills, never combine refs with frame fields. The gap is that a large share of the guidance concerns the upload panel and other tools rather than when to call generate_image itself, which dilutes the when-not signal.

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

All agent-media 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