Skip to main content

Upload videos

A file goes from your code straight to storage, never through the API, in parts: large files upload in pieces you can send side by side and try again one at a time. It takes three calls and an editor token.

1. Create the video​

Say what the file is: its name and size in bytes. Everything else (folder, labels, who may watch it, which formats to encode, a workflow to run) is optional; see Create Video for all of it, and What to pick below.

curl https://your-crumbcast/api/v1/projects/$PROJECT_ID/videos/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Launch day", "name": "launch.mp4", "size": 734003200, "content_type": "video/mp4"}'

The answer has the new video, and how to cut the file in upload:

{
"video": { "id": "3f2b9c1e-…", "title": "Launch day", "…": "…" },
"upload": { "part_size": 16777216, "part_count": 44 }
}

Parts are numbered from 1; each is part_size bytes, but the last, which is the rest.

2. Upload the parts​

Ask for each part's URL (up to 100 at a time), then PUT the part's bytes to it. The URLs are good for an hour: ask again for any that run out.

curl https://your-crumbcast/api/v1/videos/$VIDEO_ID/upload/parts/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"part_numbers": [1, 2, 3]}'
{ "urls": [{ "part_number": 1, "url": "https://…" }, "…"] }

The part URLs are your storage's, not the API's: send them no Authorization header.

3. Complete the upload​

Once every part is in:

curl -X POST https://your-crumbcast/api/v1/videos/$VIDEO_ID/uploaded/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN"

Complete Upload puts the parts together and starts encoding. This answers 409 while any part is missing: upload it, then call again.

A webhook tells you when the video plays (video.ready) and when every format is done (video.encoded).

With an SDK​

The JavaScript, Python and PHP SDKs make the three calls in one, with the parts sent four at a time, each tried again on its own:

import { openAsBlob } from "node:fs";
import { Crumbcast } from "crumbcast";

const crumbcast = new Crumbcast({ token: process.env.CRUMBCAST_TOKEN!, baseUrl: "https://your-crumbcast" });

const video = await crumbcast.uploadVideo(projectId, await openAsBlob("launch.mp4"), {
title: "Launch day",
name: "launch.mp4",
});

All together, in Python​

Without an SDK, the same three calls with requests:

import math
import os

import requests

API = "https://your-crumbcast/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CRUMBCAST_TOKEN']}"


def upload(project_id: str, path: str, title: str) -> dict:
size = os.path.getsize(path)
created = session.post(
f"{API}/projects/{project_id}/videos/",
json={"title": title, "name": os.path.basename(path), "size": size},
)
created.raise_for_status()
video, plan = created.json()["video"], created.json()["upload"]

numbers = list(range(1, plan["part_count"] + 1))
with open(path, "rb") as file:
# Up to 100 part URLs at a time
for start in range(0, len(numbers), 100):
signed = session.post(
f"{API}/videos/{video['id']}/upload/parts/",
json={"part_numbers": numbers[start:start + 100]},
)
signed.raise_for_status()
for part in signed.json()["urls"]:
file.seek((part["part_number"] - 1) * plan["part_size"])
# Storage's URL: no Authorization header
requests.put(part["url"], data=file.read(plan["part_size"])).raise_for_status()

started = session.post(f"{API}/videos/{video['id']}/uploaded/")
started.raise_for_status()
return started.json()

A file that's already online needs no upload: Crumbcast downloads it.

curl https://your-crumbcast/api/v1/projects/$PROJECT_ID/videos/import/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/launch.mp4", "title": "Launch day"}'

It answers 202 with the new video at once; the download and encoding follow. If the file can't be fetched, the video is deleted and a video.errored webhook says why.

Videos on Vimeo or YouTube come over from a connected account, with their titles and thumbnails: see Migrating to Crumbcast.

Replacing a video's file​

Replace Video File uploads a new file in place of a video's, in the same parts, ending with the same uploaded/ call. The video plays as it was until the new file is encoded; its ID, links and settings stay.

What to pick​

Uploads and imports take the same choices, each optional:

FieldWithout it
folder_id, label_idsWhere it's filed (Modify videos)The top level, no labels
playback_policy, passwordWho may watch (Access and permissions)public
protectionclear, aes or drmclear
watermarksA logo, forensic marks, or bothNone
encodingsOne to three formats: codec (h.264, h.265, av1), max_quality (the short side, e.g. 1080), bitrate (standard, high, max)H.264, up to the source's quality
normalize_audioIts sound brought to one loudnessOff
storage_idWhere its files are kept for good: one of GET /projects/{id}/storages/ (a workflow with a storage puts them there instead)The project's default storage
metadataKey-value pairs of your own, such as a customer's IDNone
workflow_idA workflow: its choices in place of these, and its steps run once the file is inNone

A choice your plan doesn't have answers 402, before anything is uploaded.

On Sandbox, the plan you start on before adding a card, every new video is a Sandbox video: once its file is in, it's cut to its first 30 seconds (source_state stays importing meanwhile), its renditions carry Crumbcast's logo, marked for test purposes, and it's deleted at its expires_at, 7 days later. Enough to build your upload, playback and webhooks against. Once you add a card (Free never charges it), POST /videos/{id}/keep/ keeps one for good, encoded again without the mark; new videos are whole from then on.

Following it along​

A video's source_state says where its file is: awaiting_upload, importing, then ready. Then each of its formats goes from queued to started to completed (or error), and plays once it's playable: a format plays before every rendition of it is done. The webhooks say each step, so you don't have to ask: video.ready once it plays, video.encoded once nothing of it is encoding any more.