Sending images in JSON APIs

Published 2026-11-10 · Base64 vs multipart vs presigned URLs

JSON has no binary type. When an API schema wants an image inside a JSON body, the bytes have to become text, and Base64 is the standard way to do it. That works — the OpenAI vision and Google Cloud Vision endpoints both accept Base64-encoded images — but it is worth knowing what the encoding costs, why so many APIs demand it anyway, and when multipart or object storage is the better move.

The short version: Base64 in JSON is fine for thumbnails and for API contracts that require it, and expensive for multi-megabyte payloads that don't.

What Base64 does to a JSON payload

Base64 encodes every 3 bytes as 4 characters, so the string is 33.3% larger than the file before any transport. A 1 MB photo becomes a roughly 1.33 MB string. Nothing you do to the JSON changes that ratio — it is arithmetic, not overhead you can tune away. Measured Base64 overhead walks through the numbers for several image formats.

JSON escaping, at least, adds nothing on top. The Base64 alphabet — A–Z, a–z, 0–9, plus +, /, and padding = — needs no escaping inside a JSON string, so there are no \u sequences and no doubled quotes. The inflation stops at exactly the encoding ratio.

The structural cost is subtler. A typical payload looks like this:

{
  "title": "Receipt scan",
  "image": {
    "mime_type": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

The image is one enormous token in a document that parsers typically materialize in memory as a single string. Most frameworks cannot stream into a field or index into it; logging the request body dumps the whole blob; and a debugging session that prints the payload becomes useless. If the API validates the string before decoding, the server holds the 1.33x string and the decoded bytes at the same time.

A related question is why the image cannot ride in the URL instead. URLs have practical length limits across clients and intermediaries, and a request line carrying a megabyte of encoded image is unreliable. Image payloads belong in request bodies, and in a JSON API the body is Base64.

Why APIs require it anyway

Given the costs, the number of JSON APIs that accept Base64 images needs explaining. Three reasons dominate:

  • One request, one schema. Everything travels in a single JSON document: metadata, options, and the image together. There is no second endpoint and no multipart parser, and the payload survives proxies and gateways that only understand JSON.
  • Framework gravity. JSON in, JSON out is what most web frameworks do best. Keeping an endpoint pure JSON keeps validation, auth middleware, and error responses uniform.
  • Vision models. The LLM image-input APIs are JSON-first. OpenAI's chat completions accept an image_url content part whose URL can be a full data URI — data:image/png;base64,… — which is the pattern in our OpenAI vision Base64 image guide. Google's Cloud Vision takes raw Base64, no data: prefix, in the image.content field of an images.annotate request; the Cloud Vision Base64 image page has the exact body, and the endpoint's request-size limits apply.

Some ticketing and messaging APIs also accept Base64 attachments in their create-object payloads, while several of the same products reject Base64 for uploads and insist on multipart. Read the docs for the specific object type before building around it — the same product can support both shapes on different endpoints.

There is also a size reality to respect. APIs that accept Base64 usually document a request-size ceiling, and that ceiling is enforced on the encoded string, not the original file. If a framework or gateway limits request bodies, the effective image limit is roughly three quarters of it after encoding — plan for the encoded size, not the file size.

The alternatives and their trade-offs

multipart/form-data

The classic upload format. Image bytes go over the wire as raw binary in one part, with metadata in the other parts. No encoding tax, and servers can stream the part to disk or storage instead of buffering a giant string. Browsers speak it natively through FormData, and most HTTP libraries handle it in a line or two. The cost is that the endpoint stops being pure JSON: some gateways, some test tooling, and some team conventions treat multipart as a separate beast to configure.

Presigned URLs and direct-to-storage uploads

The API issues a short-lived signed URL; the client uploads the bytes straight to object storage and sends only the resulting key or reference back. Your API never touches the image bytes, so there is no decode cost, no body-size limit to negotiate, and no memory spike — at the price of an extra round trip, client-side upload logic, and expiry details to get right. This is the standard architecture once files get large or traffic grows.

Binary body with metadata in headers

For single-image endpoints: the raw image bytes are the request body with an image/* Content-Type, and metadata travels in custom headers or query parameters. It is maximally efficient — zero encoding overhead — and appropriately uncommon. Serializers, proxies, and logging middleware that assume JSON need explicit handling, so it fits purpose-built endpoints better than general CRUD APIs.

Hybrid patterns

Real systems often combine the options. A common split: create the record in JSON, then upload the bytes in a second call to an upload URL the first response returns. It keeps the metadata endpoint clean, lets the binary step use multipart or plain binary, and makes retries cheap because only the failing step repeats. If you control the API design, this pattern delivers most of the direct-upload benefits without a storage dependency.

Matching transport to size and endpoint

Choosing a transport for images in APIs
ScenarioBetter transportWhy
Thumbnail or icon under roughly 100 KB inside a JSON recordBase64 in JSONOne round trip, one schema; the 33% costs little at this size
Multi-megabyte photo, scan, or screenshotmultipart or presigned uploadSkips the encoding tax and the server-side decode peak
Synchronous ML or vision APIWhatever the contract documentsRaw Base64 or a data URI, exactly as specified — not a place to improvise
Client uploads, API keeps bookkeepingPresigned URL to storageBytes bypass the API entirely; it sees only a reference
Single-image endpoint with tight bandwidthBinary body plus header metadataNo encoding overhead at all

Reading the table, the boundary is less about a specific byte count and more about who pays for what. Base64 in JSON pushes cost onto the client (a bigger upload), the server (decode memory), and the log pipeline all at once; multipart shifts the cost to endpoint complexity; presigned uploads shift it to an extra round trip and client code. Pick where the cost is cheapest for your traffic shape.

Practical tips

  • Send the shape the docs ask for. Some APIs want raw Base64; others want the full data: URI including the prefix. They are not interchangeable — the wrong shape usually means a 400 response. Our image to Base64 for API guide shows both shapes for the common endpoints.
  • Budget for decode on the server. Decoding turns a 1.33 MB string into 1 MB of bytes, and with concurrent uploads those memory peaks stack. Enforce a request-size limit that matches the real use case, and release the string after decoding.
  • Shrink before you encode. Resizing or compressing first helps every transport, but it matters most for Base64, where the encoding tax multiplies whatever you send. If the target is a hard ceiling, compressing an image to 100 KB and then encoding usually beats negotiating with transport-level tricks.
  • Don't count on request compression. Responses get gzip or Brotli routinely; request bodies usually do not. Some servers accept compressed requests and some clients can send them, but in most setups a Base64 payload travels at full size — plan sizes accordingly.
  • Respect body-size limits on the encoded string. Frameworks and gateways enforce request limits on the wire format, and Base64 rides inside the JSON body. A limit that looks generous for metadata gets tight once an image is inside it — size the limit for the encoded payload.
  • Truncate logs. A single debug line containing a full Base64 body can dwarf everything else in your log store. Log the field's length and a short prefix instead.

When Base64 in JSON makes sense

  • Use it when the API contract requires it — including LLM vision endpoints — when the images are small, tens to a few hundred kilobytes, and when you want one request, one schema, and no upload machinery.
  • Avoid it when payloads reach into the megabytes, clients are mobile on metered connections, you need streaming or resumable uploads, or object storage is already part of the stack. Multipart or presigned uploads are cheaper in bytes, memory, and patience.
  • In between, compress or resize first and re-measure. The measured overhead page helps you put a number on the decision before you commit an endpoint design to it.