Import generated videos from an external URL

Goal

Store your own copy of an external video and retain its Assets ID independently of the provider URL.

Prerequisites

A direct HTTPS file URL that returns the video bytes, not a webpage
A server-side Assets token with assets:write and an authorized space
A destination bucket and enough storage allowance

Workflow

Wait for the external generator to finish and obtain its direct download URL.

Create a fresh capability allowing remote URL ingestion.

Fetch the source into Assets before the source URL expires.

Persist the returned asset ID, wait for readiness and use Assets delivery URLs.

Choose a usable source URL

The source must be reachable from StackShift and return HTTP 200 with an allowed Content-Type. The importer does not accept custom Authorization headers or browser cookies for the upstream server. If the provider requires those, download the bytes on your backend and upload the file normally, or request a provider-signed download URL. Remote ingestion protects against private-network destinations. Do not use localhost, internal IPs or a URL that resolves to your private services. Use the final direct media URL rather than a share page or an HTML redirect/login flow. URL expiry must leave time for the complete fetch.

Create a remote-ingestion capability

Run this on your backend. The example uses jq to read the success/data envelope. Set STACKSHIFT_ASSETS_TOKEN and STACKSHIFT_ASSET_SPACE_ID in a protected environment. Replace the bucket, prefix and origin with your application values. Use a new unique object key for every generated result. Unlike a general API key, this token is restricted to the specified origin and upload policy. Do not log the token or the provider download URL; either may grant temporary access.

set -euo pipefail
API='https://api.stackshift.cloud'
CAPABILITY=$(curl --fail-with-body -sS -X POST "$API/api/v1/assets/upload-capabilities" \
  -H "Authorization: Bearer $STACKSHIFT_ASSETS_TOKEN" \
  -H "X-Asset-Space-ID: $STACKSHIFT_ASSET_SPACE_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "bucket": "generated-videos",
    "key_prefix": "generated/user_123",
    "allowed_mime_types": ["video/mp4"],
    "allowed_origins": ["https://app.example.com"],
    "max_bytes": 104857600,
    "allow_remote_url": true,
    "expires_in": "15m"
  }' | jq -er '.data.token')

Copy the generated video

Set GENERATED_VIDEO_URL to the external provider download URL on your server. This request waits for ingestion and returns an asset record; it does not return a background import job. Keep the connection open while the file is transferred. The 100 MiB limit above is an example, not a platform-wide allowance. The Origin must match the capability even when you call from a backend. Browser callers supply it automatically. Remote URL ingestion must use a fresh capability that has not been bound to a chunked session.

jq -n --arg url "$GENERATED_VIDEO_URL" \
  --arg key "generated/user_123/result-unique-id.mp4" \
  '{url: $url, key: $key}' | \
curl --fail-with-body -sS -X POST "$API/assets/widget/remote-url" \
  -H "Authorization: Bearer $CAPABILITY" \
  -H 'Origin: https://app.example.com' \
  -H 'Content-Type: application/json' \
  --data-binary @- > imported-video.json
jq -er '.data.id' imported-video.json

Permanent storage versus a permanent URL

Successful ingestion stores the file in the destination Assets bucket. The external generator URL may expire afterward without removing your Assets copy. Keep the returned asset ID and manage it through normal storage, retention and deletion rules; permanent storage does not mean an undeletable file. Check the new asset status, scan and processing readiness. If it needs video editing or playback, prepare the current version through the native video API. Follow trim and poster recipes for subsequent edits. A private asset needs an authorized download URL; an expiring URL is not the permanent identifier. Public delivery requires an intentional public bucket/asset policy and readiness. Your application should not advertise the original provider URL as the stored result.

Retries and rejected sources

Remote ingestion does not expose the chunked-session Idempotency-Key contract. If a connection fails after the transfer may have succeeded, first look up the exact destination bucket/key using your backend and reconcile the asset. Do not generate another key and blindly repeat the import. A source served as application/octet-stream will fail a capability limited to video/mp4. Prefer a provider URL with the correct media Content-Type or download and upload through your backend; do not broaden all customer upload policies merely to make one provider response pass. The current remote capability endpoint accepts url and key; it does not accept a custom maximum video duration, upstream headers or a visibility override. Bucket/content rules and subsequent video validation still apply.

Expected result

Store your own copy of an external video and retain its Assets ID independently of the provider URL.

Common failures

An HTML share page is not a direct video download.
Expired source URLs, private-network destinations, non-200 responses or MIME mismatches reject ingestion.
A successful transfer still needs scan/processing readiness; it does not bypass video review or plan limits.

Secure browser video uploads

Issue constrained upload credentials from your backend, upload video chunks from the browser, and distinguish enforced file limits from duration checks.

Trim videos, create JPG posters and download MP4s

Copyable REST recipes for start/end trimming with audio, timestamp JPEG posters, job polling and signed download URLs for external AI services.

Private assets and signed URLs

Keep files private, mint version-bound download tokens, and avoid accidentally caching or logging protected media.

Cloudinary, S3, R2, and S2 migrations

Inventory, dry-run, import, deduplicate, retry, cancel, and report durable migrations from Cloudinary or S3-compatible storage into StackShift Assets.

​Goal

​Prerequisites

​Workflow

​Choose a usable source URL

​Create a remote-ingestion capability

​Copy the generated video

​Permanent storage versus a permanent URL

​Retries and rejected sources

​Expected result

​Common failures

​Related guides

Secure browser video uploads

Trim videos, create JPG posters and download MP4s

Private assets and signed URLs

Cloudinary, S3, R2, and S2 migrations

Goal

Prerequisites

Workflow

Choose a usable source URL

Create a remote-ingestion capability

Copy the generated video

Permanent storage versus a permanent URL

Retries and rejected sources

Expected result

Common failures

Related guides