Base64 Output (enable_base64_output)

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

Parameter Definition

How It Works

When enable_base64_output = true:

• The output field contains base64-encoded strings that decode directly to the raw file bytes
• No data:<mime>;base64, prefix is included — feed the entire string into your base64 decoder
• Each output (image, video, audio) is a separate base64 string in the array
• The MIME type is implied by the model — the same as the file you would have downloaded from the URL

When enable_base64_output = false (default):

• The output field contains CDN URLs you can download directly
• Lower latency, smaller payload

Compatibility

If you submit a request with both webhook and enable_base64_output: true, the API responds:

HTTP 400 Bad Request
{
  "error": "webhook callback does not support base64 output, please use the normal API to use base64 output"
}

To use base64 with async tasks, omit webhook and poll GET /api/v3/predictions/:id instead.

ℹ️ 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.

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
 
# `prediction["output"][0]` is the base64 string
img_bytes = base64.b64decode(prediction["output"][0])
with open("out.png", "wb") as f:
    f.write(img_bytes)

JavaScript / Node.js

const fs = require("fs");
 
const imgBytes = Buffer.from(prediction.output[0], "base64");
fs.writeFileSync("out.png", imgBytes);

Browser

// For inline display, prepend the data URI yourself:
const dataUri = `data:image/png;base64,${prediction.output[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 round-trip to the CDN

Stick with the URL default when:

• You’re using webhook callbacks (base64 is rejected anyway)
• The output is large (>5 MB raw) — embedding it in JSON inflates payloads ~33%
• You only need to forward / re-host the output (the URL is already on our CDN)

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

You’ll get a 400 immediately. Switch to polling GET /api/v3/predictions/:id, or drop enable_base64_output and download from the URL on your side.

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 blocking requests
• Get Result — polling pattern for async tasks