<!-- Markdown twin of https://pixelvault.dev/ai-agent-image-upload/ -->

AI agents

# 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).

[Get a free API key](/signup/) [All agent integrations](/for-ai-agents/)

## 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.

Method

Works in

API key

[curl / plain HTTP](#curl)

Any agent with a shell or an HTTP client

Not needed (links last 30 days)

[CLI](#cli)

Agents that can run shell commands

Yes, register once

[MCP server](#mcp)

Claude, Cursor and any MCP client

Yes, as a Bearer token

[Agent skill](#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](/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](/docs/cli/).

\# 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](/docs/mcp/) and [MCP image hosting](/blog/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](/blog/host-images-with-your-coding-agent/). The full list of skills is on the [skills page](/skills/).

\# 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](/blog/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](/for-ai-agents/), [why regular image hosts fail agents](/blog/image-hosting-for-ai-agents/), [image hosting API](/image-hosting-api/), and the free browser tool [image to URL](/tools/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](/pricing/) for paid plans.

[Get a free API key](/signup/)
