Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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.

{ "data": {
  "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.

MethodWorks inAPI key
curl / plain HTTPAny agent with a shell or an HTTP clientNot needed (links last 30 days)
CLIAgents that can run shell commandsYes, register once
MCP serverClaude, Cursor and any MCP clientYes, as a Bearer token
Agent skillClaude Code, Codex, Cursor and anything that reads SKILL.mdYes, 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.

# No account, no key. The URL is at .data.url in the response.
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.

# Register once (writes your API key to the CLI config), then upload:
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 Code. Cursor and other MCP clients take the same URL and header.
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.

# Install once; the agent discovers the skill files on its own.
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.

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