Skip to main content
Most renders and tasks reference media via source_url. You have three options:
  1. Public URL you control — host the file yourself (S3, GCS, CDN, etc.) and pass that URL directly in render/task requests.
  2. Framelane upload — upload a local file with POST /v1/uploads, then use the returned source_url.
  3. Framelane import — copy a remote file (public URL, Dropbox/Google Drive share link, or YouTube) with POST /v1/imports.
This page covers local uploads only. For remote URLs, see Importing remote media.

​
Upload flow

POST /v1/uploads  →  PUT bytes to upload_url  →  use source_url in render/task

​
1. Request an upload URL

curl -X POST https://api.framelane.io/v1/uploads \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "video/mp4",
    "filename": "my-clip.mp4"
  }'
Response (201 Created): 
{
  "upload_url": "https://storage.googleapis.com/...",
  "source_url": "https://cdn-user.framelane.io/uploads/ws_01J.../a1b2c3.mp4",
  "expires_at": "2026-05-29T08:00:00Z"
}
The upload_url expires in 1 hour.

​
2. Upload the file bytes

PUT the entire file to upload_url with the same Content-Type you declared in step 1. Bytes go directly to GCS — they never pass through the Framelane API. 
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @my-clip.mp4
Use a single PUT request (not multipart form upload).

​
3. Use source_url in your job

Pass source_url from the upload response as source_url in any render element or task body: 
{
  "type": "video",
  "id": "clip1",
  "source_url": "https://cdn-user.framelane.io/uploads/ws_01J.../a1b2c3.mp4"
}
For video and audio uploads, Framelane extracts metadata (duration, codecs) asynchronously after the PUT completes. You can submit a render immediately; if metadata is not ready yet, the job stays queued until it is.

​
Supported content types

CategoryMIME types
Videovideo/mp4, video/quicktime, video/webm, video/x-msvideo, video/x-matroska, video/mpeg
Audioaudio/mpeg, audio/mp4, audio/wav, audio/x-wav, audio/aac, audio/flac, audio/ogg
Imageimage/jpeg, image/png, image/webp, image/gif, image/tiff
Fontfont/ttf, font/otf, font/woff, font/woff2
Unsupported content_type values return 422 with an unsupported_content_type error.

​
Errors

CodeCause
unsupported_content_typeMIME type not in the allowed list
401Missing or invalid API key