# Base64 Encoder & Decoder — Text, Files & Data URIs (`eliai/base64-encoder-decoder`) Actor

Encode text or remote files to Base64 (with ready-to-use data: URIs), or decode Base64 back to text and downloadable files. Batch input, URL-safe variant, strict validation. From $0.0002 per item; failed items never charged.

- **URL**: https://apify.com/eliai/base64-encoder-decoder.md
- **Developed by:** [Anthony Snider](https://apify.com/eliai) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 8 total users, 7 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Base64 Encoder & Decoder — Text, Files & Data URIs

Convert **text or remote files to Base64** — including a ready-to-paste `data:` URI — or **decode Base64 back** to text or a downloadable file. Built for pipelines: batch input, strict validation, URL-safe (base64url) support, and per-item billing where **failed items are never charged**.

### What it does

**Encode mode**

- Encodes any text to Base64 (standard or URL-safe RFC 4648 §5 alphabet).
- Downloads any public file URL and returns its Base64 **plus a complete `data:<mime>;base64,...` URI** you can drop straight into an `<img src>`, a CSS `url()`, a JSON payload, or an email.
- Large results (over ~3 MB of Base64) are stored in the run's key-value store and the dataset row carries a direct download URL instead, so dataset limits never truncate your data.

**Decode mode**

- Accepts standard Base64, base64url, whitespace-littered Base64, and full `data:` URIs — all normalized automatically.
- Valid UTF-8 payloads come back as plain text in the dataset.
- Binary payloads (or any payload when **Store decoded file** is on) are written to the key-value store with the content type detected from magic bytes (PNG, JPEG, GIF, WebP, PDF, ZIP, XML…), and the row gives you a direct download URL.
- Input that is **not** valid Base64 is reported as an error row — recorded, never charged. The actor validates before decoding; it will not hand you silently-corrupted output the way a plain `Buffer.from(s, 'base64')` would.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `mode` | `encode` | `decode` | `encode` | |
| `text` | string | sample text | One text to encode, or a Base64 string / data URI to decode |
| `items` | string\[] | `[]` | Batch — one dataset row per item |
| `fileUrls` | string\[] | `[]` | Encode mode: public files to download & encode |
| `urlSafe` | boolean | `false` | Output base64url (`-`/`_`, no padding). Decode accepts both alphabets always |
| `decodeToFile` | boolean | `false` | Decode mode: always store the decoded bytes as a downloadable file |
| `maxFileSizeMb` | integer | `25` | Skip downloads larger than this (recorded, unbilled) |

### Example output (encode, file URL)

```json
{
  "mode": "encode",
  "url": "https://example.com/logo.png",
  "contentType": "image/png",
  "inputBytes": 4123,
  "base64": "iVBORw0KGgoAAAANSUhEUg...",
  "dataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "alphabet": "standard",
  "processedAt": "2026-08-03T19:20:00.000Z"
}
```

### Run it from the API

```bash
curl -X POST "https://api.apify.com/v2/acts/<username>~base64-encoder-decoder/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"encode","fileUrls":["https://example.com/logo.png"]}'
```

### Pricing

Pay per event: a fraction of a cent per text item and per file. **Anything that fails — bad Base64, dead URLs, oversized downloads — is recorded in the dataset but never billed.** Data is written before the charge, so even a run that hits your spending limit keeps everything it produced.

### Honest limits

- File downloads are capped at `maxFileSizeMb` (max 100 MB) and 60 s per file.
- Content-type detection covers common formats by magic bytes; unknown binaries are stored as `application/octet-stream` — the bytes are always exact, only the label can be generic.
- This actor fetches only the public URLs you explicitly supply — no crawling, no login-walled content.

### FAQ

**How do I convert an image URL to a Base64 data URI?** Encode mode with the URL in `fileUrls` — the result includes the raw Base64 **and** a complete `data:<mime>;base64,...` URI ready for an `<img src>`, CSS `url()`, JSON payload, or email.

**How do I decode a Base64 string back to a file?** Decode mode — UTF-8 payloads come back as plain text; binary payloads are stored with the content type detected from magic bytes (PNG, JPEG, PDF, ZIP, ...) and the row carries a direct download URL.

**What's URL-safe Base64 and when do I need it?** The RFC 4648 §5 alphabet (`-`/`_` instead of `+`/`/`, no padding) — required in URLs, JWTs, and filenames. Set `urlSafe` for encoding; decoding accepts both alphabets automatically.

**What happens with invalid Base64 input?** It's validated before decoding and reported as an error row — recorded, never charged, and never the silently corrupted bytes a plain `Buffer.from(s, 'base64')` would hand you.

**Is there a size limit for files?** `maxFileSizeMb` caps downloads (default 25 MB, max 100 MB, 60 s each); oversized results over ~3 MB of Base64 are stored in the key-value store with a download URL so dataset limits never truncate your data.

# Actor input Schema

## `mode` (type: `string`):

`encode` turns text or files into Base64. `decode` turns Base64 back into text (or a downloadable file — see Store decoded file).

## `text` (type: `string`):

A single text to encode — or a Base64 string to decode. Data URIs (`data:...;base64,xxxx`) are accepted in decode mode. Leave empty if you only use Batch items or File URLs.

## `items` (type: `array`):

Process many texts (or Base64 strings) in one run — one dataset row each.

## `fileUrls` (type: `array`):

Public file URLs to download and encode to Base64. Each result includes the raw Base64, a ready-to-paste `data:` URI, the content type and the byte size. Encode mode only.

## `urlSafe` (type: `boolean`):

Use `-` and `_` instead of `+` and `/` and drop `=` padding (RFC 4648 §5). Decode mode accepts both alphabets automatically regardless of this setting.

## `decodeToFile` (type: `boolean`):

In decode mode, store the decoded bytes in the run's key-value store and return a direct download URL. The file type is detected from magic bytes (PNG, JPEG, GIF, WebP, PDF, ZIP, …).

## `maxFileSizeMb` (type: `integer`):

Downloads larger than this are skipped (recorded, never charged).

## Actor input object example

```json
{
  "mode": "encode",
  "text": "Hello from Apify! Base64 encoding keeps binary data safe inside JSON, URLs and email.",
  "items": [],
  "fileUrls": [],
  "urlSafe": false,
  "decodeToFile": false,
  "maxFileSizeMb": 25
}
```

# Actor output Schema

## `results` (type: `string`):

Every item this run produced, as JSON.

## `resultsCsv` (type: `string`):

The same items as a spreadsheet-ready CSV.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("eliai/base64-encoder-decoder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("eliai/base64-encoder-decoder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call eliai/base64-encoder-decoder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eliai/base64-encoder-decoder"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3UhrH3ItLIhaCV4tM/builds/3rA3sYBA0k9PjIH5a/openapi.json