Uploads

Choose a media input

Each single-file media field accepts one of these forms:

Input	Example	Requirement
Beeble URI	`beeble://uploads/your-upload-id/source.png`	Finish the upload in the same organization before use.
Beeble CDN URL	`https://cdn.beeble.ai/public/developer-api/reference.png`	Use an owned file, an original signed URL granting access, or a public sample.
HTTPS URL	`https://storage.example.com/source.png?signature=...`	Publicly readable or presigned; custom authentication headers are not supported.
Base64 data URI	`data:image/png;base64,...`	At most 50 MiB of decoded media. Use the file’s MIME type.

Pass the value directly in the model’s media field, such as inputs.source, inputs.reference_image, or a supported audio reference. No separate upload is required for HTTPS or data: inputs. For private Beeble CDN files, use a URL you own or preserve the complete signed URL that grants access. The URL alone does not grant access to another user’s private file. Public CDN samples can be used directly without a signature. For inline files, create the complete URI before submitting the request:

# Encode a local PNG. Remove base64 line breaks before putting it in JSON.
SOURCE_URI="data:image/png;base64,$(base64 < source.png | tr -d '\r\n')"

import base64

with open("source.png", "rb") as source:
    source_uri = "data:image/png;base64," + base64.b64encode(source.read()).decode("ascii")

// Run in Node.js. Use the MIME type of the actual file.
import { readFile } from "node:fs/promises"

const sourceUri =
  "data:image/png;base64," + (await readFile("source.png")).toString("base64")

Use the complete value as the media field in the JSON request body. For audio, use data:audio/mpeg;base64,... for MP3 or data:audio/wav;base64,... for WAV; the selected model must support that audio input. External HTTPS imports have a 5 GiB file limit and a 120-second download budget; large files or slow origins should use an upload URL instead. Private network destinations and redirects to them are refused. The selected model’s file type, size, dimensions, and duration limits also apply. Requests with multiple external references may share a shorter download budget, so upload large reference sets first. Keep presigned URLs readable and their contents unchanged through estimation and submission. Separate estimate and job requests can fetch the same URL again. Estimates can import and store media, but do not create jobs or charge credits. Image-sequence directory inputs still require a Beeble cache URI.

Create an upload URL

Request parameters, body, and response schema Set BEEBLE_API_KEY and, for internal teams, BEEBLE_TEAM_ID. Use the same organization and team when submitting the job. Python requires requests; JavaScript examples run in Node.js.

curl --fail-with-body https://api.beeble.ai/v1/uploads \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}" \
  -H "Content-Type: application/json" \
  --data '{"filename": "source.png"}'

import os
import requests

headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
if team_id := os.environ.get("BEEBLE_TEAM_ID"):
    headers["X-Beeble-Team-Id"] = team_id

response = requests.post(
    "https://api.beeble.ai/v1/uploads",
    headers=headers,
    json={"filename": "source.png"},
    timeout=30,
)
response.raise_for_status()
upload = response.json()
print(upload["beeble_uri"])

import { readFile } from "node:fs/promises"

const headers = {
  "x-api-key": process.env.BEEBLE_API_KEY,
  "Content-Type": "application/json",
}
if (process.env.BEEBLE_TEAM_ID)
  headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
const response = await fetch("https://api.beeble.ai/v1/uploads", {
  method: "POST",
  headers,
  body: JSON.stringify({ filename: "source.png" }),
  signal: AbortSignal.timeout(30_000),
})
if (!response.ok) throw new Error(await response.text())
const upload = await response.json()
console.log(upload.beeble_uri)

Response (200):

{
  "id": "upload_example",
  "upload_url": "https://storage.example.com/source.png?signed-parameters",
  "beeble_uri": "beeble://uploads/upload_example/source.png"
}

Upload the file

Send the file to the returned upload_url. This example uses a PNG image; use the matching content type for other files. Do not send your API key to this URL. For models with audio references, upload .mp3 with Content-Type: audio/mpeg or .wav with Content-Type: audio/wav, then pass the returned Beeble URI in the model’s audio field. Audio uploads do not change SwitchX’s image/video inputs.

UPLOAD_URL="https://storage.example.com/source.png?signed-parameters" # Use your upload_url.
curl --fail-with-body --request PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @source.png

with open("source.png", "rb") as source:
    uploaded = requests.put(
        upload["upload_url"],
        headers={"Content-Type": "image/png"},
        data=source,
        timeout=120,
    )
uploaded.raise_for_status()

const uploaded = await fetch(upload.upload_url, {
  method: "PUT",
  headers: { "Content-Type": "image/png" },
  body: await readFile("source.png"),
  signal: AbortSignal.timeout(120_000),
})
if (!uploaded.ok) throw new Error(await uploaded.text())

Use the media in a job

After the upload succeeds, use beeble_uri in the model’s media input, usually inputs.source. Continue with the Quickstart.

Media requirements

Match the model’s supported media types, dimensions, and duration.
SwitchX source and custom-alpha uploads must not exceed 5 GB.
Complete uploads before requesting an estimate or submitting a job.

Source metadata

SwitchX, Background Remover, VFX Passes, SDR to HDR, and Reframe measure the source automatically. You can omit generation_type and frame_count; if you supply a media type, it must match the file. Other models follow their input_schema. Reframe still requires all six canvas and source-placement fields. See Reframe.

Metadata returned by estimates

source_metadata includes media type, width, height, and frame count, plus frame rate and duration for video. frame_count_exact: false means the count was calculated from duration and frame rate. Products without source measurement return source_metadata: null.

See the Upload API Reference for the full schema.

Get started

Products

Core concepts

Integrations

Choose a media input

Create an upload URL

Upload the file

Use the media in a job

Media requirements

Source metadata

​Choose a media input

​Create an upload URL

​Upload the file

​Use the media in a job

​Media requirements

​Source metadata

Choose a media input

Create an upload URL

Upload the file

Use the media in a job

Media requirements

Source metadata