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)".
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:
| Field | Meaning |
|---|---|
url (request) | The public http(s) image URL to fetch. Required — omitting it returns 400 {"error":"url required"}. |
success | true on a completed fetch. |
filename | Generated name (image-<timestamp>.<ext>) derived from the upstream content type. |
size | Byte length of the fetched image. |
mime | Content type reported by the remote server, defaulting to image/jpeg. |
data | The 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.
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.
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.
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:
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:
http and https are accepted, and URLs carrying embedded usernames or passwords are rejected outright.localhost and private, loopback, link-local, CGNAT, and reserved ranges (including cloud metadata endpoints) are refused — the same class of address that turns an innocent "fetch this image" feature into an internal port scanner.127.0.0.1 fails instead of succeeding.Content-Length header and while streaming, so a lying header cannot exhaust memory.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.
Four things this endpoint does not do, so you can plan around them:
image/* and reports whatever the remote server actually sends, MIME type included. A URL that returns HTML will arrive as base64 HTML; check mime before you treat it as a picture.width argument and send it in the body; the current server route ignores it — treat the proxy as a pure fetch.)500 with a short reason string rather than a specific 403 or 413. Upstream HTTP errors are clearer: a non-2xx response from the origin becomes 400 with the origin's status code.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.
| You want | Use |
|---|---|
| A single image's bytes | POST /api/agent/image-proxy |
| Readable text from a page | POST /api/article-extract |
| Specific fields from a page | POST /api/structured-scrape |
| Every image or video on a page | POST /api/agent/scrape |
| A video file | POST /api/agent/video-download |
| Durable storage for a remote file | POST /api/artifact with a url |
| An image you already have locally | Upload 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.
Run the same tools in the browser, or call them from your agent with an API key.
Open toolbox