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. The renderer fetches it as-is. For video/audio referenced this way you must set out_point (Framelane can’t probe the duration of a file it doesn’t host).
  2. Framelane upload — upload a local file with POST /v1/uploads, then use the returned source_url.
  3. Auto-ingest a public URL — set ingest_external: true on a render and Framelane copies any non-Framelane source_url into your storage before rendering. See Importing public URLs below.
This page covers local uploads (option 2) and auto-ingest (option 3).

​
Upload flow

​
1. Request an upload URL

Response (201 Created):
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.
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:
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.

​
Importing public URLs

If a render references a source_url that Framelane doesn’t host, set ingest_external: true on the render and Framelane copies each such file into your storage before rendering. This gives you the reliability and metadata of a Framelane-hosted file (including automatic out_point for video/audio) without a separate upload step.
How it behaves:
  • The render is created in the ingesting state and is not sent to the render engine yet.
  • Framelane copies each non-Framelane source file into your storage. You receive an asset.ready webhook per file as it completes.
  • Once every imported file is ready, the render automatically transitions to queued and proceeds. out_point is filled in from the imported file’s duration when omitted.
  • If a file can’t be imported (unreachable, too large, or unsupported), the render fails with the ingest_failed error code.
Files already hosted by Framelane (a cdn-user.framelane.io source_url from POST /v1/uploads) are never re-copied. Omit ingest_external (or set it to false) to keep the legacy pass-through behavior described in option 1 above.

​
Supported content types

Unsupported content_type values return 422 with an unsupported_content_type error.

​
Errors