← Back to blog

Remote Image Proxy API: Fetch Any Public Image from Your Agent

September 25, 2026 · Eric · 8 min read

Every agent workflow that touches an image eventually hits the same wall: the model has a URL and no way to turn it into bytes. Maybe the agent runs in a sandbox with no outbound network access. Maybe it is an MCP host where tool calls are available but raw HTTP is not. Maybe the image sits behind CORS, hotlink protection, or a redirect chain that a naive fetch chokes on. Maybe the runtime simply has no filesystem, so "download the image first" is not a step it can take.

POST /api/agent/image-proxy exists for exactly that gap. You hand it a public image URL, the platform performs the fetch server-side with the same SSRF, redirect, size, and timeout protections it applies to every other URL-taking tool, and it returns the bytes as base64 alongside the metadata your agent needs to decide what to do next. It is documented in the OpenAPI document as agentImageProxy and in the capability manifest under "Image Proxy (Agent API)".

What the call actually returns

The endpoint takes an agent API key (Authorization: Bearer mt_…) and a JSON body with one required field, url. The response carries the image, not just a pointer to it:

FieldMeaning
url (request)The public http(s) image URL to fetch. Required — omitting it returns 400 {"error":"url required"}.
successtrue on a completed fetch.
filenameGenerated name (image-<timestamp>.<ext>) derived from the upstream content type.
sizeByte length of the fetched image.
mimeContent type reported by the remote server, defaulting to image/jpeg.
dataThe image itself, base64-encoded, inline in the JSON response.
usage{used_today, limit, plan} for the agent key that made the call.

That in-band usage block is worth noticing: an autonomous agent can read its own remaining daily allowance from the same response it just used, instead of discovering the ceiling through a 429.

Quick start with curl

The first command fetches an image and prints only the metadata, so a 20 MB picture never scrolls through your terminal:

export AMT_AGENT_KEY="mt_your_key_here"

curl -s -X POST https://agentmediatools.com/api/agent/image-proxy \
  -H "Authorization: Bearer $AMT_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agentmediatools.com/images/og-blog.jpg"}' \
  | jq '{filename, mime, size, used_today: .usage.used_today, limit: .usage.limit}'

The second writes the decoded bytes straight to disk by piping the base64 field through base64 -d:

curl -s -X POST https://agentmediatools.com/api/agent/image-proxy \
  -H "Authorization: Bearer $AMT_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agentmediatools.com/images/og-blog.jpg"}' \
  | jq -r '.data' | base64 -d > remote-image.jpg

Swap in any public image URL — a user avatar, a product photo, a chart rendered by another service, a screenshot CDN link. The proxy does not cache or remember the URL, so the same call repeated still counts as a call.

Python: fetch, decode, then chain into another tool

The proxy is most useful as the first step of a chain. Many media endpoints on the platform accept multipart file uploads rather than URLs, so the decoded bytes are what unlock them — resize, OCR, EXIF stripping, vision description, durable artifact storage. Here is a complete loop that pulls a remote image, writes it to a temp file, and hands it to the resize endpoint:

import base64
import requests

KEY = "mt_your_key_here"
BASE = "https://agentmediatools.com"
HEADERS = {"Authorization": f"Bearer {KEY}"}

# 1. Fetch a remote image through the proxy
fetched = requests.post(
    f"{BASE}/api/agent/image-proxy",
    headers=HEADERS,
    json={"url": "https://agentmediatools.com/images/og-blog.jpg"},
    timeout=60,
)
fetched.raise_for_status()
payload = fetched.json()
print(payload["filename"], payload["mime"], payload["size"], payload["usage"])

# 2. Decode the base64 payload to a real file
with open("remote-image.jpg", "wb") as fh:
    fh.write(base64.b64decode(payload["data"]))

# 3. Hand that file to a multipart tool (resize by width)
with open("remote-image.jpg", "rb") as fh:
    resized = requests.post(
        f"{BASE}/api/resize-image",
        headers=HEADERS,
        files={"image": ("remote-image.jpg", fh, payload["mime"])},
        data={"width": 1200},
        timeout=120,
    )
resized.raise_for_status()
print(resized.json()["downloadUrl"])

/api/resize-image answers with {success, filename, filesize, downloadUrl}, where downloadUrl is a served path under /downloads/ you can pass to a human or feed into the next step. The same pattern works for /api/ocr, /api/strip-exif, and /api/describe-image — all multipart, all accepting the same agent key.

Why not just fetch the image myself?

If your agent runs in a normal container with network access, a two-line requests.get is still cheaper than any API call, and you should keep doing that. The proxy earns its keep in the environments where you cannot:

The guardrails are the product

A server-side fetcher is also a server-side liability, so the fetch path is deliberately narrow. These are the behaviours a fetcher has to get right, and they are enforced before the request leaves the platform:

Keys, quota, and what a call costs

This is an agent-authenticated endpoint: it requires a Bearer key, because an unauthenticated open fetcher is an abuse magnet. Missing credentials return 401 {"error":"Missing or invalid Authorization header. Use: Bearer <agent-key>"}, an unknown key returns 401, and a revoked key returns 403.

Each successful call counts as one tool use against that key's daily limit — 25 per day on a free key, 1,000 per day on a Pro key — and it is not a credit-metered tool. When a key's daily allowance is exhausted, the platform attempts to cover the call with a usage credit instead of failing immediately; if no credit is available you get a 429 with the current usage counters. The usage block in the response tells an agent exactly where it stands.

Honest limitations

Four things this endpoint does not do, so you can plan around them:

There is also no MCP tool for this endpoint today — unlike most of the platform's media routes, you will call it over REST from your own harness rather than through a tool name. The Agent Hub lists which capabilities are exposed as native tools.

Pick the right fetcher for the job

You wantUse
A single image's bytesPOST /api/agent/image-proxy
Readable text from a pagePOST /api/article-extract
Specific fields from a pagePOST /api/structured-scrape
Every image or video on a pagePOST /api/agent/scrape
A video filePOST /api/agent/video-download
Durable storage for a remote filePOST /api/artifact with a url
An image you already have locallyUpload it directly to the tool you need

The proxy is the narrow tool: one URL in, one image's bytes out, with the safety work done for you. Everything downstream — thumbnailing, OCR, vision captioning, archiving — is a separate call, and the whole chain fits comfortably inside a single agent turn.

Try it in the Toolbox

Run the same tools in the browser, or call them from your agent with an API key.

Open toolbox