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:
- JavaScript
- Python
- PHP
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",
});
import os
from crumbcast import Crumbcast
crumbcast = Crumbcast(token=os.environ["CRUMBCAST_TOKEN"], base_url="https://your-crumbcast")
video = crumbcast.upload_video(project_id, "launch.mp4", {"title": "Launch day"})
use Crumbcast\Crumbcast;
$crumbcast = new Crumbcast(token: getenv('CRUMBCAST_TOKEN'), baseUrl: 'https://your-crumbcast');
$video = $crumbcast->uploadVideo($projectId, 'launch.mp4', ['title' => 'Launch day']);
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()
Importing from a link
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:
| Field | Without it | |
|---|---|---|
folder_id, label_ids | Where it's filed (Modify videos) | The top level, no labels |
playback_policy, password | Who may watch (Access and permissions) | public |
protection | clear, aes or drm | clear |
watermarks | A logo, forensic marks, or both | None |
encodings | One 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_audio | Its sound brought to one loudness | Off |
storage_id | Where 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 |
metadata | Key-value pairs of your own, such as a customer's ID | None |
workflow_id | A workflow: its choices in place of these, and its steps run once the file is in | None |
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.