Media

Import a video from a link

Gives us a public HTTPS link to a video file and we fetch it for you. The video starts as uploading while we download it, then moves on like any upload. Poll the video until it's ready. A workspace can have 5 imports running at once.

post/media/imports

Request

  • Base URL: https://api.deploy.social/v1
  • URL: https://api.deploy.social/v1/media/imports
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Any unique string, like a UUID. Send the same request again with the same key within 24 hours and you get the first response back instead of a second post.

Example:5f0c7a1e-8d0b-4c0e-9d8a-1c2b3a4d5e6f

Request body

urlstring required

A public HTTPS link straight to the video file (MP4, MOV, WebM, AVI or MTS), up to 1 GB. A page that plays the video won't work.

filenamestring

What to call the file. Defaults to the name at the end of the link.

Example request

{
  "url": "https://example.com/videos/studio-update.mp4"
}

Response

The new video, downloading.

idstring required

The video's id. Starts with media_.

kind'video' | 'image' required

video or image. New kinds may be added.

statusstring required

uploading until the file arrives, processing while we prepare it, then ready or failed. expired means its files were removed after a period of inactivity; upload it again to use it. New values may be added.

filenamestring nullable required
content_typestring nullable required
size_bytesinteger nullable required
duration_secnumber nullable required
widthinteger nullable required
heightinteger nullable required
created_atstring date-time required

When the video was added.

updated_atstring date-time required

When the video last changed.

Example response

{
  "id": "media_cmf3k0m2b0000ab12cd34ef56",
  "kind": "video",
  "status": "ready",
  "filename": "studio-update.mp4",
  "content_type": "video/mp4",
  "size_bytes": 48213377,
  "duration_sec": 42.5,
  "width": 1080,
  "height": 1920,
  "progress": {
    "phase": "transcoding",
    "percent": 62
  },
  "created_at": "2026-10-01T15:00:00.000Z",
  "updated_at": "2026-10-01T15:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.