Use imports when the file lives on the internet and you do not have a local copy to upload. Framelane copies the file into your workspace storage and returns a source_url you can use in renders and tasks — the same CDN URL shape as POST /v1/uploads.
For files on your machine, use Uploading media instead.
How it works
POST /v1/imports → processing → GET /v1/imports/{id} or asset.ready webhook → use source_url
status: processing. When the file is in storage and metadata is ready (for video/audio), you receive an asset.ready webhook or can poll until status is ready.
Import flow
1. Start an import
curl -X POST https://api.framelane.io/v1/imports \
-H "Authorization: Bearer $FRAMELANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.dropbox.com/s/abc123/clip.mp4?dl=0"
}'
202 Accepted):
{
"id": "import_01J8QR2K5VKDGN2T4FBM3CZYX7",
"status": "processing",
"source_url": null,
"created_at": "2026-05-29T08:00:00Z"
}
filename hints the desired extension when the remote URL does not include one.
2. Wait for completion
Poll the import:
curl https://api.framelane.io/v1/imports/import_01J8QR2K5VKDGN2T4FBM3CZYX7 \
-H "Authorization: Bearer $FRAMELANE_API_KEY"
{
"id": "import_01J8QR2K5VKDGN2T4FBM3CZYX7",
"status": "ready",
"source_url": "https://cdn-user.framelane.io/uploads/ws_01J.../a1b2c3.mp4",
"error": null
}
asset.ready — same event as after a direct upload.
3. Use source_url in your job
{
"type": "video",
"id": "clip1",
"source_url": "https://cdn-user.framelane.io/uploads/ws_01J.../a1b2c3.mp4"
}
asset.ready usually fires as soon as the import finishes.
For YouTube imports (Oxylabs), metadata is extracted the same way as direct uploads (async probe after the file lands in GCS). You can submit a render immediately; if metadata is not ready yet, the job stays queued until it is.
Supported sources
Framelane routes each URL to the appropriate backend automatically.
| Source | Example | Backend |
|---|
| Direct HTTPS file URL | https://cdn.example.com/clip.mp4 | Transloadit |
| Dropbox share link | https://www.dropbox.com/s/... | Transloadit |
| Google Drive share link | https://drive.google.com/file/d/... | Transloadit |
| Google Docs export link | https://docs.google.com/... | Transloadit |
| OneDrive share link | https://onedrive.live.com/... | Transloadit |
| YouTube | https://www.youtube.com/watch?v=..., https://youtu.be/... | Oxylabs (direct to GCS) |
Transloadit (public and share links)
Transloadit fetches the remote file and stores it in your workspace bucket. Share links from Dropbox, Google Drive, and OneDrive are resolved to the actual file, not an HTML preview page.
YouTube (Oxylabs)
YouTube cannot be imported through Transloadit. For YouTube URLs, Framelane uses the Oxylabs YouTube Downloader, which downloads the video and uploads it directly to Framelane GCS storage — bytes never pass through the Framelane API server.
curl -X POST https://api.framelane.io/v1/imports \
-H "Authorization: Bearer $FRAMELANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}'
You are responsible for ensuring you have the right to download and process content from any URL you submit, including YouTube videos.
Choosing upload vs import
| Situation | Endpoint |
|---|
| File on disk / in your app | POST /v1/uploads |
| Public HTTPS URL or cloud share link | POST /v1/imports |
| YouTube URL | POST /v1/imports |
| File already on your own CDN | Pass that URL directly as source_url in renders/tasks (no import) |
Errors
| Code / status | Cause |
|---|
422 invalid_request | URL is not HTTPS, malformed, or unsupported |
422 invalid_source | Remote URL unreachable or not a downloadable file |
import status: failed | Transloadit assembly error or Oxylabs download failed — see error on GET /v1/imports/{id} |
asset_not_ready | Import finished but metadata probe still running — retry render or wait for asset.ready |
401 | Missing or invalid API key |
