How an AI agent uploads an image
and gets a URL.
Short answer: the agent POSTs the file as multipart form data to an image-hosting API and reads the URL from the response. With PixelVault it is one call, it needs no account or API key, and the CDN URL is at .data.url:
curl -F "file=@screenshot.png" https://api.pixelvault.dev/v1/images
Keyless links last about 30 days. Add a free API key for managed images with no fixed expiration (free-plan retention applies).
What the agent gets back
A JSON envelope with the image under data. The public URL is data.url, on img.pixelvault.dev, and it works as the src of an image tag, in Markdown, in a pull request or in an og:image meta tag.
"id": "img_xyz789",
"url": "https://img.pixelvault.dev/proj_abc123/img_xyz789.png",
"temporary": true, // keyless upload: expires in 30 days
…
} }
Four ways to do it
Pick by what your agent can already do. All four end at the same URL.
| Method | Works in | API key |
|---|---|---|
| curl / plain HTTP | Any agent with a shell or an HTTP client | Not needed (links last 30 days) |
| CLI | Agents that can run shell commands | Yes, register once |
| MCP server | Claude, Cursor and any MCP client | Yes, as a Bearer token |
| Agent skill | Claude Code, Codex, Cursor and anything that reads SKILL.md | Yes, set up once |
1. curl or any HTTP client
The fastest path and the only one that needs no setup. Works from Python, Node or any language too: see the image upload API for Node and Python examples.
curl -s -F "file=@screenshot.png" https://api.pixelvault.dev/v1/images | jq -r '.data.url'
# → https://img.pixelvault.dev/proj_abc123/img_xyz789.png
2. The CLI
One command per file, --json for output an agent can parse. Details in the CLI docs.
npx pixelvault-cli register
npx pixelvault-cli upload screenshot.png --json
3. The MCP server
The agent calls upload as a native tool, with no shell and no HTTP details to get right. Setup and the tool list are in the MCP docs and MCP image hosting. A remote server can't read files on your disk, so for local files use the CLI or the skill alongside it.
claude mcp add --transport http pixelvault \
https://mcp.pixelvault.dev/mcp \
--header "Authorization: Bearer pv_live_xxx"
# The agent now has upload_image, list_images, get_image, delete_image… as tools.
4. The agent skill
Teaches the agent the endpoint, auth and response shape once, so every later session just says "host this image". Walkthrough: host an image with your coding agent. The full list of skills is on the skills page.
npx skills add pixelvault-dev/skill
# Then, in the session:
/pixelvault-setup
/pixelvault-upload screenshot.png
Where agents go wrong
Four small details that an agent re-derives, and sometimes gets wrong, in every fresh session.
Wrong host
Uploads go to api.pixelvault.dev. The img.pixelvault.dev domain only serves images that already exist.
Wrong body
The single-image endpoint takes multipart form data with a file field. JSON and base64 bodies fail with a 400. Base64 is accepted only by the batch endpoint, with an API key.
Wrong path in the response
The URL is at data.url, inside the data envelope, not at the top level. Reading the wrong path yields undefined and a confident wrong answer.
Linking before hosting
A local path, a localhost URL or a data: URI only works on the agent's own machine. Host the image first, then put the returned URL in the PR, doc or post.
Unverified-account cap
A brand-new account can upload 5 images before email verification is required. Verify once and the cap lifts.
Cloud or remote agents
An agent running in the cloud or over SSH can use the same call: see getting images into cloud coding agents.
AI agent image upload FAQ
How does an AI agent upload an image and get a URL?
It sends the image to an image-hosting API and reads the URL from the response. With PixelVault that is one call: POST the file as multipart form data to https://api.pixelvault.dev/v1/images and read data.url from the JSON that comes back. The call works without an account or API key.
Can an AI agent upload an image without an API key?
Yes. A multipart file upload to POST /v1/images works with no key and returns a public CDN URL. Keyless uploads are temporary and expire after about 30 days. Register for a free API key to get managed images without that fixed expiration, plus URL imports, batches and private images. Free-plan retention applies.
How does Claude Code upload an image and get a link?
Claude Code can run the curl call above from its shell, use the pixelvault-cli command line tool, call the upload_image tool on the PixelVault MCP server, or run /pixelvault-upload from the PixelVault skill. The skill and the MCP server need an API key; the plain curl call does not.
Why does my agent get a 400 when it uploads an image?
The usual cause is sending JSON or base64 to the single-image endpoint. POST /v1/images expects multipart form data with the file in a field named file. The other frequent mistake is reading the URL from the top level of the response; it is at data.url. To import from a public URL instead of a file, send a JSON body with a url field and an API key.
Can an agent upload an image from a URL instead of a file?
Yes, with an API key. POST a JSON body such as {"url":"https://example.com/source.png"} to /v1/images and PixelVault fetches it. The URL must be public https; private and internal addresses are blocked. The batch endpoint also accepts base64 data.
Can ChatGPT upload images to PixelVault?
Through a Custom GPT Action backed by the PixelVault API. The setup steps and the Actions spec are in the ChatGPT guide at /docs/chatgpt/.
How long does the URL last?
A keyless upload lasts about 30 days. An upload made with a free API key has no fixed expiration, subject to free-plan retention. Set expires_in on a keyed upload to make scratch images delete themselves after a time you choose.
Is it free?
The free tier includes 200 MB of storage, 500 uploads a month and 1 GB of bandwidth, with no credit card. Egress is never billed. See the pricing page for paid plans.
Related: media hosting for AI agents, why regular image hosts fail agents, image hosting API, and the free browser tool image to URL for a one-off file.
Give your agent a place to put images
Free tier: 200 MB storage, 500 uploads/month, no credit card. See pricing for paid plans.
Get a free API key