Docs › Import from a URL

Import from a URL

Instead of uploading a file, send a public HTTPS URL and the API downloads it. The file is checked once it arrives and processed immediately, just like an upload. Processing options (trim, redactions, deleteOriginal) go in the request.

The URL must be HTTPS and resolve only to public internet addresses. The file size limit is the same as uploads (20 GiB by default). The server must answer 200 with the file (at most 3 redirects, each re-checked); Dropbox share links need ?dl=1, and presigned S3 links work fine.

POST /videos
{ "sourceUrl": "https://example.com/videos/tutorial.mp4", "fileName": "tutorial.mp4", "maxHeight": 1080 }

201 Created
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "status": "SUBMITTED",
  "fileName": "tutorial.mp4", "statusPath": "/videos/3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f" }

Unlike an upload, there is no parts step or complete call. Dry runs (?dryRun=true) validate the URL without downloading. While the download is in progress the video record has no sourceVersionId; it fills in from the receipt once the file arrives. The download is retried once on network errors; 4xx and size-limit errors are permanent.

AUTH="Authorization: Bearer $VIDEO_API_KEY"; JSON="Content-Type: application/json"

# Create the video from a URL
VIDEO_ID=$(curl -s -X POST "$VIDEO_API/videos" -H "$AUTH" -H "$JSON" \
  -d '{"sourceUrl":"https://example.com/videos/tutorial.mp4","fileName":"tutorial.mp4","maxHeight":1080}' | jq -r .videoId)

# Poll status until ready
until [ "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .status)" != "RUNNING" ]; do sleep 10; done

# Download
curl -s -o tutorial-processed.mp4 "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .downloadUrl)"

import os, time, requests

API, KEY = os.environ["VIDEO_API"], os.environ["VIDEO_API_KEY"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {KEY}"

video = session.request("POST", API + "/videos", json={
    "sourceUrl": "https://example.com/videos/tutorial.mp4",
    "fileName": "tutorial.mp4",
    "maxHeight": 1080
}, timeout=60).json()
video_id = video["videoId"]

status = {"status": "SUBMITTED"}
while status["status"] in ("SUBMITTED", "RUNNING"):
    time.sleep(10)
    status = session.request("GET", API + f"/videos/{video_id}", timeout=60).json()

if status["status"] != "SUCCEEDED":
    raise RuntimeError(f"Processing ended with {status['status']}")

with requests.get(status["downloadUrl"], stream=True) as download, open("tutorial-processed.mp4", "wb") as out:
    for chunk in download.iter_content(1024*1024):
        out.write(chunk)

Limits and errors

URL format: must be HTTPS, 1–2,048 characters, with no username or password embedded.
Redirects: at most 3; each destination is checked the same way (HTTPS, public internet).
Content-Length: checked up front; if the declared size exceeds the limit, the import fails immediately.
Network errors: retried once (e.g. timeout, connection reset). Other errors are permanent: 404, size limit hit, empty file, DNS failure, private address.
No camera / streaming: imports work only with single files. Use regular uploads for screen + camera or upload-while-recording.
Idempotency: `Idempotency-Key` works the same way as for uploads and edits.