How to Intermediate · 3 min read

How to use base64 image with Claude API

Quick answer

The Claude API does not natively process base64 images as direct inputs. To use a base64 image with anthropic, you must decode or reference the image externally and include relevant textual descriptions or metadata in the messages. Claude models primarily handle text, so embed base64 images as text strings or convert them to accessible URLs for context.

PREREQUISITES

Python 3.8+
Anthropic API key
pip install anthropic>=0.20

Setup

Install the official Anthropic Python SDK and set your API key as an environment variable.

bash

pip install anthropic>=0.20

Step by step

Claude models do not directly process images but accept text input. To use a base64 image, include the base64 string as part of the user message or decode it externally and provide a textual description. Below is a Python example sending a base64 image string as text to Claude.

python

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# Example base64 image string (truncated for brevity)
base64_image = "iVBORw0KGgoAAAANSUhEUgAAAAUA..."

system_prompt = "You are a helpful assistant that can interpret base64 image data as text."
user_message = f"Here is a base64 encoded image:\n{base64_image}\nPlease describe what this image might be."

response = client.messages.create(
    model="claude-3-5-haiku-20241022",
    max_tokens=500,
    system=system_prompt,
    messages=[{"role": "user", "content": user_message}]
)

print(response.content[0].text)

output

Here is a description or interpretation of the base64 image data as text...

Common variations

Use external image hosting and provide URLs in the prompt instead of base64 strings.
Preprocess base64 images with an OCR or image recognition model, then send the extracted text to Claude.
Use async calls with the anthropic SDK for non-blocking requests.

python

import asyncio
import os
import anthropic

async def main():
    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
    base64_image = "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    system_prompt = "You are a helpful assistant that can interpret base64 image data as text."
    user_message = f"Here is a base64 encoded image:\n{base64_image}\nPlease describe what this image might be."

    response = await client.messages.acreate(
        model="claude-3-5-haiku-20241022",
        max_tokens=500,
        system=system_prompt,
        messages=[{"role": "user", "content": user_message}]
    )
    print(response.content[0].text)

asyncio.run(main())

output

Here is a description or interpretation of the base64 image data as text...

Troubleshooting

If the response does not interpret the base64 image meaningfully, consider preprocessing the image with a dedicated vision model and sending the extracted text instead.
Ensure your base64 string is correctly formatted and not truncated.
Check your API key and environment variable setup if authentication errors occur.

✅

Key Takeaways

Claude API primarily processes text; embed base64 images as text or references.
Use the system parameter to guide Claude on how to interpret base64 data.
Preprocess images externally for better results when image understanding is required.

Verified 2026-04 · claude-3-5-haiku-20241022

Verify ↗