Skip to content
agent-media docs
IntroductionStart here: what Agent Media does and which path to follow.↵QuickstartConnect, check your account, upload references and generate.↵Core conceptsAccounts, connectors, tools, models, credits and jobs.↵Connect your agentClaude, Claude Code, ChatGPT, Codex, Cursor and MCP setup.↵Agent workflowThe sequence from request to finished media.↵Tool referenceTools, arguments and schemas from the official connector.↵Upload imagesMultiple reference images, drag and drop, 24-hour expiry.↵Choose a modelVideo modes, image models, audio, supported inputs and limits.↵Write better promptsRealism, framing and reference guidance.↵RecipesProduct images, talking heads and consistent characters.↵Account and billingPaid credits, account checks, payments and draft recovery.↵Generation pricingQuotes and model costs.↵REST APIAuthentication, endpoints and OpenAPI.↵Jobs and retriesRecover timeouts without duplicate generations.↵
Public documentation · No sign-in required
Documentation / Upload reference images

Creating media

Upload reference images

Drag and drop multiple images, then use them in a generation.

On this page

Open the existing upload panel

Ask your agent to open Agent Media’s upload panel. It should call open_upload_panel when available, or upload_image with an empty object for an older cached catalog. Use the returned browser link if the client cannot display the embedded panel.

Open the Agent Media image upload panel. I want to upload reference photos. Do not generate yet.

Drop in your images

Drop one or more images into the panel, or choose them using the file picker. A session accepts up to 10 images, up to 25 MB each. Wait until each upload is marked ready and check the displayed expiry. The panel supports images, not video or audio.

Use the images in generation

Tell the agent when the images are ready. It retrieves them with get_uploads, or the panel retrieval instructions returned by upload_image. It must pass the exact returned image URLs into the next generation.

  1. Image editing or composition: use refs in generate_image.
  2. Start a video from one photo: use first_frame in generate_video.
  3. Reference-guided video: use refs with a model and mode that supports them.
  4. Quote the intended inputs and continue only within the generation you authorized.

Let the agent see and remember the uploads

Retrieving an upload session returns small image previews directly in the tool response, alongside the original generation URLs. The agent should inspect these previews before describing the product or writing an image-specific prompt. It does not need to open the image host with a web-fetch tool. Previews are for inspection; generation must use the original image_url.

If the agent loses the session ID, ask it to call get_uploads with an empty object. Older connectors can call upload_image with upload_key set to panel:recent. This lists unexpired sessions on your account; retrieve the session that matches your request. If multiple sessions could match, the agent should ask which one instead of silently mixing references.

If a preview cannot be retrieved or the client cannot display images, the agent should explain the limitation without guessing from your email address, filename or account details. Your original upload URLs remain available until expiry.

Private storage and 24-hour expiry

Images are stored temporarily in private object storage and accessed through restricted URLs. The session and all its image URLs expire 24 hours after the session was created; an image added later has less time remaining. Anyone holding a valid restricted image URL can use it until it expires, so treat it as private. Re-upload an expired reference before another generation.

If the agent stops after upload

Tell it to retrieve the uploaded images and use their returned URLs in the generation you already requested. It should not build another upload page or ask you to paste base64 into chat.

Use the images from this Agent Media upload session as references for the generation I requested. Retrieve their URLs, quote the request, and continue within my approved budget.