Base64 Output (enable_base64_output)

This document describes the behavior, limitations, and compatibility of base64 output mode in API requests.

enable_base64_output is a global request option: it works with every model and is sent in the request body alongside the model’s own parameters. Model pages do not list it in their parameter tables.

Parameter Definition

How It Works

When enable_base64_output = true, each item in outputs is handled on its own:

• The order and number of items in outputs are the same as without base64 output.
• The MIME type is the same as the file you would have downloaded from the URL.
• To tell whether a file output is base64 or still a URL, check whether the string starts with http:// or https://.
• Base64 is meant to be read right after the task finishes. Poll the result within 24 hours of completion to receive base64; later requests return the output URLs as stored.

When enable_base64_output = false (default):

• File outputs are URLs you can download directly
• Lower latency, smaller payload

Compatibility

Requests that combine a standard_webhook or webhook query parameter with "enable_base64_output": true are rejected. Webhooks always deliver output URLs. To retrieve base64 for an async task, omit the webhook and poll GET /api/v3/predictions/:id/result.

ℹ️ Why? Webhook payloads are pushed to your endpoint and embedded base64 (often 1–10 MB per output) tends to break receivers with payload-size limits. URLs keep webhook deliveries small and reliable. See How to Use Webhooks.

Limits When Polling for Base64

Each base64 response downloads and encodes every output file again, so GET /api/v3/predictions/:id/result limits how often one task’s outputs are converted:

• Only responses that return a completed task’s outputs as base64 count. Polling while the task is still running does not, and neither does the sync mode response.
• A request over either limit receives HTTP 429 with a Retry-After header giving the seconds to wait.
• Decode and save the files from the first base64 response instead of requesting the result again.

Format

The returned string is just the standard base64 alphabet — no MIME prefix, no line breaks. Decode the entire string as-is.

Python

import base64
 
item = prediction["outputs"][0]
if isinstance(item, str) and not item.startswith(("http://", "https://")):
    with open("out.png", "wb") as f:
        f.write(base64.b64decode(item))
else:
    print("Output was returned as-is:", item)  # a URL (too large or not fetchable) or a non-file value

JavaScript / Node.js

const fs = require("fs");
 
const item = prediction.outputs[0];
if (typeof item === "string" && !/^https?:\/\//.test(item)) {
  fs.writeFileSync("out.png", Buffer.from(item, "base64"));
} else {
  console.log("Output was returned as-is:", item); // a URL (too large or not fetchable) or a non-file value
}

Browser

// For inline display, prepend the data URI yourself:
const dataUri = `data:image/png;base64,${prediction.outputs[0]}`;
document.getElementById("preview").src = dataUri;

When to Use Base64

Choose base64 when:

• You want the output inline in the response without a follow-up download
• You’re integrating with a system that consumes base64 directly (e.g., SDKs that render images in-browser)
• You need to avoid an extra download request

Stick with the URL default when:

• You’re using webhook callbacks and want smaller callback payloads
• The output is large (>5 MB raw) — embedding it in JSON inflates payloads ~33%. Files larger than 64 MiB are always returned as URLs
• You only need to forward or re-host the output (the URL is already hosted)

Common Pitfalls

Forgot the prefix is gone

If your code still strips a data:image/png;base64, prefix, that’s now a no-op — the string is already naked. No action needed, but you can simplify the code.

Tried to use it with a webhook

Requests that combine a webhook with enable_base64_output are rejected; webhooks always deliver output URLs. If your application needs base64, poll GET /api/v3/predictions/:id/result, or drop enable_base64_output and download from the URL on your side.

Assumed every output is base64

Text, JSON, and number outputs are never encoded, and a file that is larger than 64 MiB or cannot be fetched is still returned as a URL. Check for an http:// or https:// prefix before decoding.

Decoded only part of the string

The full string is base64 — don’t truncate or split on commas/whitespace. Pass it directly to your decoder.

Related

• How to Use Webhooks — webhook callback details and why base64 isn’t supported there
• Sync Mode — enable_sync_mode for single-request result attempts
• Get Result — polling pattern for async tasks