Base64 Encoder & Decoder

🔐 Base64 Encoder & Decoder – Bulk Base64 Encoding, Decoding & File Conversion API

The Base64 Encoder & Decoder is a batch conversion Actor that turns plain text and remote files into Base64 strings, and turns Base64 strings back into their original bytes. Instead of pasting one value at a time into a browser tool, you hand the Actor a list of text inputs or file URLs, pick a mode, and receive a structured dataset with the converted payload, byte sizes and a processing timestamp for every item.

Base64 encoding is the standard way to move binary data through channels that only tolerate text — JSON payloads, email MIME parts, data URIs, JWT segments, webhook bodies, environment variables and API request fields. This Base64 encoder and decoder wraps that transformation in an API-callable job so it can run inside a data pipeline, a scheduled workflow or an automation platform rather than a browser tab. Large or binary results can be written to the key-value store instead of being inlined, which keeps datasets readable and avoids bloating rows with megabytes of encoded content.

The Actor accepts two independent input channels — raw strings and remote URLs — and processes both in a single run. Each result carries its own error field, so one malformed Base64 string or one dead download link never aborts the whole batch.

---

📊 What Data Can You Extract with This Base64 Encoder & Decoder?

Every dataset row describes one conversion: what went in, what came out, how big both were, and whether anything went wrong.

Category	Fields	What it gives you
Source payload	input, inputType	The original string or file URL that was processed, plus whether it arrived as text or as a downloaded file.
Converted result	output	The Base64 string (encode mode) or the decoded original content (decode mode), returned inline.
File-based result	outputFileKey	The key-value store record key holding the result when outputAsFile is enabled — used instead of inline output.
Size accounting	inputSizeBytes, outputSizeBytes	Exact byte counts before and after conversion, useful for quota and payload-limit checks.
Run context	mode, processedAt	Which direction the conversion ran and the ISO timestamp when the item was handled.
Failure diagnostics	error	A human-readable message for the specific item that failed; null on success.

The pairing of inputSizeBytes and outputSizeBytes is the field combination most people underuse. Base64 inflates payloads by roughly a third, and knowing the exact encoded size ahead of time tells you whether an attachment will fit inside an API body limit, an SQS message, a Lambda payload or a database column before you try to send it.

---

🌟 Key Features of the Base64 Encoder & Decoder

Feature	Description
🔁 Two-way conversion	A single mode switch flips the whole run between encode and decode, so one Actor covers both directions of your pipeline.
📚 Batch processing	Pass an entire list to textInputs and every string is converted in one run, producing one dataset row per item.
🌐 Remote file support	fileUrls downloads files over HTTP and encodes their raw bytes, so images, PDFs and archives never have to touch your machine.
💾 Key-value store output	Enable outputAsFile and results are stored as key-value store records, with outputFileKey pointing at each one.
📏 Byte-size reporting	inputSizeBytes and outputSizeBytes are recorded for every item so you can audit payload growth precisely.
🛡️ Per-item error isolation	A failure writes an error message on that row only; the remaining items in the batch still complete.
🕒 Timestamped records	processedAt stamps each conversion in ISO 8601, giving you an audit trail inside the dataset itself.
🚦 Managed proxy handling	Remote downloads are routed through automatically rotated proxies, so URL fetching is handled without extra configuration.
🔌 API-first design	Every run is callable over the Apify API, meaning the Base64 encoder and decoder plugs into existing scripts and schedulers.

---

🚀 Why Choose This Base64 Encoder & Decoder?

Batch conversion instead of one-off pasting. Browser-based Base64 tools handle a single value at a time and give you nothing structured back. This Actor takes an arbitrarily long list, converts every entry, and returns a queryable dataset with sizes, timestamps and error status attached to each row.

Remote files without local downloads. The fileUrls input downloads and converts files server-side. You can encode a set of image URLs, certificate files or documents straight into Base64 without pulling them onto a laptop first, which matters when the pipeline runs inside a scheduler or a serverless function.

Predictable handling of large payloads. Inlining a multi-megabyte Base64 string into a dataset row makes the dataset painful to browse and export. The outputAsFile option redirects those results into the key-value store and leaves a compact outputFileKey reference behind, so the dataset stays lightweight.

Failure-tolerant batches. Base64 decoding is unforgiving — one stray character invalidates the string. Rather than failing the run, this Base64 encoder and decoder records the problem in the item's error field and moves on, so a 500-item batch is never lost to a single bad entry.

---

📥 Input

{
  "mode": "encode",
  "textInputs": [
    "Hello World",
    "scraperhubapi@gmail.com"
  ],
  "fileUrls": [
    "https://example.com/assets/logo.png"
  ],
  "outputAsFile": false
}

🔧 Base64 Encoder & Decoder Input Fields

Field	Type	Required	Default	Description
mode	string (encode | decode)	✅ Yes	encode	Whether to encode input into Base64 or decode Base64 input back to its original form.
textInputs	array of strings	No	[]	List of plain text strings (encode mode) or Base64 strings (decode mode) to process.
fileUrls	array of strings	No	[]	List of remote file URLs to download and process. In encode mode the raw file bytes are Base64-encoded; in decode mode the file content is treated as Base64 text and decoded.
outputAsFile	boolean	No	false	If enabled, each result's output is stored as a record in the default key-value store (outputFileKey holds the record key) instead of being returned inline in the output field. Recommended for binary or large outputs.

💡 Input Examples

Encode a batch of short strings

{
  "mode": "encode",
  "textInputs": ["Hello World", "api-key-placeholder", "user:password"]
}

Decode Base64 back to plain text

{
  "mode": "decode",
  "textInputs": ["SGVsbG8gV29ybGQ=", "c2NyYXBlcmh1YmFwaQ=="]
}

Encode remote binary files into key-value store records

{
  "mode": "encode",
  "fileUrls": [
    "https://example.com/files/report.pdf",
    "https://example.com/images/banner.jpg"
  ],
  "outputAsFile": true
}

---

📤 Output

{
  "input": "Hello World",
  "inputType": "text",
  "mode": "encode",
  "output": "SGVsbG8gV29ybGQ=",
  "outputFileKey": null,
  "inputSizeBytes": 11,
  "outputSizeBytes": 16,
  "processedAt": "2026-08-08T15:44:40.405Z",
  "error": null
}

🧾 Base64 Encoder & Decoder Output Fields

Field	Type	Description
input	string | null	The original text string or file URL that was processed.
inputType	string | null	Whether the item came from textInputs or from a downloaded file.
mode	string | null	The conversion direction applied to this item (encode or decode).
output	string | null	The converted result returned inline. Empty when outputAsFile is enabled.
outputFileKey	string | null	Key-value store record key holding the result when outputAsFile is enabled.
inputSizeBytes	integer | null	Size of the input payload in bytes.
outputSizeBytes	integer | null	Size of the converted output in bytes.
processedAt	string | null	ISO 8601 timestamp of when the item was processed.
error	string | null	Error message if this specific item failed; null on success.

---

💻 How to Use the Base64 Encoder & Decoder (Step by Step)

Step 1: Decide Your Conversion Direction

Start by choosing the mode. Set it to encode when you have plain text or binary files that need to become Base64 — for example, embedding an image in a data URI, packing a payload into a JSON field, or building a basic-auth header. Set it to decode when you already hold Base64 strings and need the original bytes back, such as unpacking a JWT payload segment, reading an encoded webhook body, or restoring a file that was transported as text. The mode applies to the entire run, so keep encode and decode workloads in separate runs.

Step 2: Supply Your Text Inputs

Add every string you want converted to the textInputs array. Each entry becomes its own dataset row with its own sizes and error status, which makes it easy to trace a specific value later. In encode mode these should be plain UTF-8 strings; in decode mode each entry must be a valid Base64 string. Whitespace and line breaks inside Base64 blocks are common in PEM-style content, so trim your strings before submitting them if you are unsure of their origin.

Step 3: Add Remote File URLs

If your source material lives on the web rather than in a variable, populate fileUrls instead of, or alongside, textInputs. The Actor downloads each URL and processes the raw bytes it receives. Make sure the URLs are directly accessible and return the file itself rather than an HTML landing page — a link that requires a login or resolves to a redirect chain ending in a sign-in form will encode the wrong bytes. Both input channels can be used in the same run.

Step 4: Choose Inline or File Output

Leave outputAsFile at false for short strings; the converted value appears directly in the output field, which is the fastest path for scripts that read the dataset. Switch it to true when you are encoding images, PDFs, archives or anything else likely to produce a large Base64 blob. The result is then written to the default key-value store and the row carries only outputFileKey, keeping the dataset small and fast to export.

Step 5: Run the Actor and Watch the Log

Start the run from the Apify Console or over the API. The log reports progress per item, so you can see which text entries and which file URLs are being handled. For remote files, downloads dominate the runtime, so a run with many large URLs will take noticeably longer than a text-only batch of the same length.

Step 6: Review Sizes and Error Rows

Once the run finishes, sort or filter the dataset by error to isolate failures immediately. Then check inputSizeBytes against outputSizeBytes to confirm the expected ~33% growth in encode mode, or the corresponding shrink in decode mode. A decoded output that is far smaller than expected usually indicates truncated Base64 input rather than a problem with the conversion.

Step 7: Export or Pipe the Results

Export the dataset as JSON, CSV or Excel, or read it straight from the API in your own code. When outputAsFile was used, fetch each record from the key-value store using the outputFileKey value. From there the encoded payloads can be inserted into API requests, stored in a database column, or attached to downstream automation steps.

---

🔌 API Access & Integrations

Run the Base64 encoder and decoder synchronously and get the dataset items back in one call:

curl -X POST "https://api.apify.com/v2/acts/scrapers-hub~base64-encoder-decoder/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "encode",
    "textInputs": ["Hello World", "scraperhubapi@gmail.com"],
    "outputAsFile": false
  }'

The same run from Python using the official client:

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")

run_input = {
    "mode": "decode",
    "textInputs": ["SGVsbG8gV29ybGQ="],
    "outputAsFile": False,
}

run = client.actor("scrapers-hub/base64-encoder-decoder").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["input"], "->", item["output"], item["outputSizeBytes"])

Results can also be pushed into Zapier, Make, Google Sheets or Slack, or delivered to your own endpoint through Apify webhooks as soon as a run completes.

---

💡 Best Use Cases for Base64 Conversion

🖼️ Building Data URIs for Images and Icons

Encode a batch of image URLs through fileUrls and read the resulting output (or the key-value store record referenced by outputFileKey) to build data: URIs. This is the standard technique for inlining logos, favicons and small illustrations into HTML emails, single-file reports and self-contained artifacts where external image requests are blocked.

📧 Preparing Email and MIME Attachments

Transactional email APIs almost always expect attachment content as a Base64 string. Encoding your PDFs or spreadsheets ahead of time and checking outputSizeBytes against the provider's attachment ceiling prevents the classic failure where an upload is rejected only after the message is otherwise assembled.

🔑 Handling Auth Headers and Credential Blobs

Basic authentication headers, service-account key files and certificate bundles are all transported as Base64. Running mode: "encode" over a list of credential strings, or mode: "decode" over values pulled from a config store, gives you a repeatable and logged conversion step with processedAt recording exactly when it happened.

🧩 Decoding Webhook and JWT Payloads

Webhook bodies and JWT segments frequently arrive Base64-encoded. Feeding those strings into textInputs with mode: "decode" returns the readable payload in output, while the error field immediately flags any segment that was padded incorrectly or truncated in transit.

📦 Migrating Binary Assets Through Text-Only Channels

When a system only accepts JSON or plain text, binary files have to travel as Base64. Encoding a batch of fileUrls and storing the results with outputAsFile produces a set of portable, text-safe payloads plus exact inputSizeBytes and outputSizeBytes figures for planning transfer limits.

🧪 QA and Payload-Size Testing

Engineering teams often need to know how a payload grows before shipping a feature. Because every row records both byte counts, a single run over representative sample files produces a clean size table you can use to set request limits, database column widths or storage estimates.

🗂️ Bulk Normalisation in Data Pipelines

Scheduled runs can normalise incoming feeds where some fields arrive encoded and others do not. The combination of inputType, mode and error makes each conversion self-documenting, so downstream steps can trust the dataset without re-deriving what happened.

---

⚙️ Tips for Better Base64 Conversion Results

• Use outputAsFile for anything binary. Images, PDFs and archives produce very long strings; storing them as key-value store records keeps the dataset browsable and exports fast.
• Trim whitespace before decoding. Base64 copied from certificates, terminal output or wrapped email headers often carries newlines that should be stripped first.
• Check padding when decoding fails. Valid Base64 length is a multiple of four, padded with =. Truncated strings are by far the most common cause of an error value on decode rows.
• Keep encode and decode in separate runs. The mode field is run-wide, so mixing directions in one batch will produce errors on whichever half is in the wrong mode.
• Verify file URLs return the file itself. Links behind logins, share pages or redirect chains encode the HTML page rather than the intended asset — a quick check of inputSizeBytes reveals this instantly.
• Budget for ~33% growth. Encoded output is always larger than input. Compare outputSizeBytes with your destination's limit before committing to a transport format.

---

🛠️ Troubleshooting

Why is my decode run returning errors on every item? Almost always because the strings are not valid Base64. Check for missing = padding, stray whitespace or newlines, and URL-safe variants that use - and _ in place of + and /. Standard Base64 expects the latter pair.

Why is output empty but outputFileKey populated? That is the expected behaviour when outputAsFile is set to true. The converted payload lives in the default key-value store under that key; fetch it from the store rather than from the dataset row.

Why did a file URL encode to something far smaller than the actual file? The URL probably returned an HTML page — a login screen, a share landing page or an error page — instead of the raw file. Compare inputSizeBytes with the file's real size and replace the link with a direct download URL.

Why did one item fail while the rest of the batch succeeded? Each item is processed independently and records its own error. A single unreachable URL or malformed string will not stop the run. Filter the dataset by non-null error values to see exactly which entries need attention.

Why is the run slower than expected? Text conversion is near-instant; remote file downloads are not. Runtime scales with the number and size of the URLs in fileUrls and with the responsiveness of the hosts serving them.

---

❓ Frequently Asked Questions About Base64 Encoding and Decoding

What does this Base64 encoder and decoder actually do? It converts plain text and remote files into Base64 strings, and converts Base64 strings back into their original content, returning one structured dataset row per item with sizes, a timestamp and an error field.

Can I encode and decode in the same run? No. The mode field applies to the whole run. Use one run for encoding and a separate run for decoding.

How many items can I process in one run? There is no fixed cap in the input schema — textInputs and fileUrls are plain arrays. Practical limits come from run memory and the size of the files you are downloading.

Does it support binary files like images and PDFs? Yes. Put the file URL in fileUrls and the Actor downloads it and encodes the raw bytes. For binary content, enable outputAsFile so the result goes to the key-value store.

Where do results go when outputAsFile is enabled? Into the default key-value store of the run. The dataset row records the record key in outputFileKey, which you use to fetch the payload.

Can I use both textInputs and fileUrls together? Yes. Both arrays are processed in the same run, and the inputType field on each row tells you which channel the item came from.

Does the Actor use a proxy? Yes — remote file downloads are routed through automatically rotated proxies. Proxy selection is handled internally and is not exposed as an input field.

Why is my encoded output larger than the original file? Base64 represents three bytes of binary data as four ASCII characters, so encoded output is roughly 33% larger by design. The exact figures are recorded in inputSizeBytes and outputSizeBytes.

Does Base64 encoding provide any security or encryption? No. Base64 is an encoding, not encryption. Anyone can decode it trivially. Never treat Base64 as protection for secrets — use real encryption for confidential data.

Can I decode URL-safe Base64? The Actor processes standard Base64. URL-safe strings use - and _ instead of + and /, so convert those characters back before submitting the string if decoding fails.

What happens if a file URL is unreachable? That item's row records the failure in its error field and the run continues with the remaining inputs. Nothing else in the batch is affected.

Can I schedule recurring Base64 conversion jobs? Yes. Apify's scheduler can run the Actor on any cron expression, and webhooks can forward the finished dataset to your own endpoint automatically.

What output formats can I export? The dataset can be exported as JSON, JSONL, CSV, Excel, XML or HTML from the Apify Console, or read directly through the API.

How do I know when an item was processed? Each row carries processedAt, an ISO 8601 timestamp recorded at the moment that item was handled, which doubles as an audit trail inside the dataset.

Can I call this Base64 encoder and decoder from my own application? Yes. Use the standard Apify API endpoints or the official clients for Python and JavaScript; the run-sync-get-dataset-items endpoint returns the converted results in a single request.

---

🆘 Support & Feedback

Found a bug, hit an unexpected error, or need a field the Base64 encoder and decoder does not currently return? Open a ticket in the Issues tab of this Actor on Apify — issues raised there are tracked and answered directly.

Need a custom build — a different encoding scheme, a tailored output shape, or an integration wired into your own pipeline? Get in touch at scraperhubapi@gmail.com and describe what you need.

If this Actor saves you time, please leave a review on its Apify page. Ratings and written feedback genuinely shape which improvements get built next.

---

⚖️ Disclaimer

This Base64 encoder and decoder processes only the data you explicitly supply — the strings you place in textInputs and the publicly accessible URLs you place in fileUrls. It does not crawl, discover or collect data on its own, and it does not bypass authentication to reach protected files.

You are responsible for ensuring you have the right to process the content you submit. If your inputs contain personal data, you remain the data controller under the GDPR, the UK GDPR, the CCPA and any other privacy legislation that applies to you, including obligations around lawful basis, retention and data-subject rights. Base64 is an encoding, not a security control — do not rely on it to protect confidential or personal information.

When fetching remote files, make sure your use complies with the terms of service and robots policies of the hosts serving those URLs, and with any licensing that applies to the files themselves. Content you did not create or license should not be redistributed.

For questions about data handling, or to request removal of any data associated with your runs, contact scraperhubapi@gmail.com.