Skip to main content
Glama

agent-media

by ai.agent-media.api
OverviewDiscussionsAdmin

upload_image

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.

For an image already accessible to you: Store an image and get back a stable https URL you can pass to any agent-media tool. Costs NO credits. THREE ways in, in this order:

  1. FILE ON DISK (when the file is already accessible to your shell): call upload_image with file_bytes set to the exact byte size of the file (wc -c < photo.png) and file_name. You get back a put_url; run the printed curl to stream the file straight to storage, then call upload_image again with the upload_key you were given to get the URL. The bytes never pass through this conversation, so there is NO reason to resize, crop or re-encode the user’s photo first. Do not: a downscaled product photo is what the video model will show. Up to 25 MB.

  2. A URL you already have: pass image_url to re-host it.

  3. Raw bytes with no shell available: pass image_base64 (PNG or JPEG, 10 MB max after decoding). Only when 1 and 2 are impossible, and even then upload the original, never a shrunken copy. Then pass the returned URL everywhere. Do NOT paste base64 into other tool arguments or into the conversation: the client displays tool arguments to the user, so a base64 image becomes a wall of unreadable text, and every retry re-sends it.

Input Schema

NameRequiredDescriptionDefault
file_nameNoOptional with file_bytes: the file name, so the content type is right (.png or .jpg).
image_urlNoAn https URL to fetch and re-host instead.
file_bytesNoStep 1 of the file path: the exact size of the file in bytes (`wc -c < photo.png`). Returns a put_url and an upload_key. Full resolution, up to 25 MB.
upload_keyNoReuse the exact upload_key returned earlier: a panel: key retrieves all ready temporary images; a file upload key confirms the completed PUT and returns its image_url.
image_base64NoThe image bytes, base64-encoded. A `data:image/png;base64,...` prefix is accepted and stripped. Last resort: use file_bytes when you can run a shell.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior5/5

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

Goes far beyond the annotations: no generation credits consumed, 25 MB ceiling (10 MB decoded for base64), 24-hour expiry on panel images, the two-phase put_url + upload_key handshake, and the fact that file bytes bypass the conversation entirely. It also warns that image previews are not to be used for generation and that the client renders tool arguments visibly, which is non-obvious and operationally important.

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?

Substantially over-long and poorly front-loaded: the tool's actual function appears only after paragraphs of guidance about sibling tools, generation orchestration, make_ugc, and polling. Several constraints (do not poll, never infer from filename, preserve image roles) are repeated or belong to other tools' descriptions. It reads as a merged system prompt rather than a definition.

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?

Given no output schema, the description does explain what comes back (put_url, upload_key, image_url, panel: keys, expiry) and covers limits, fallbacks, expiry recovery, and handoff to generators. It is nearly complete, losing a point only because the density makes the return-value contract harder to extract than it should be.

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 coverage is 100%, so the baseline is 3, but the description adds genuine semantic layering: the three input modes are ranked by preference, and the two distinct roles of upload_key (panel: key versus file-upload completion key) are explained. The only shortfall is that the file_bytes/curl round-trip sequence is described in prose that is longer than the schema needs.

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

Purpose3/5

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

The core purpose is stated, but only in the final third: "Store an image and get back a stable https URL you can pass to any agent-media tool." The first two paragraphs are routing instructions toward open_upload_panel and get_uploads, so an agent skimming the opening might conclude this tool's job is user-interaction orchestration rather than storing an image. The verb+resource is specific once found, but it is diluted by multi-tool workflow narration.

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 when-to-use ordering is given: panel first if available, then file_bytes for a shell-accessible file, then image_url for a re-host, then image_base64 only as a last resort when 1 and 2 are impossible. When-not rules are equally explicit ("Do NOT paste base64 into other tool arguments or into the conversation", "never make a permanent copy", "do not build an upload page"). Alternatives and fallbacks are named with the conditions that select them.

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