Upload Video

Overview#

This endpoint allows you to upload brand videos to your workspace. You can upload videos from a URL, as a base64-encoded string, or as a binary upload.

https://api.orshot.com/v1/brand-assets/videos/add

Request#

await fetch("https://api.orshot.com/v1/brand-assets/videos/add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    file: "https://example.com/videos/brand-intro.mp4",
    name: "brand-intro.mp4", // optional
    tags: ["intro", "brand"], // optional
    metadata: { // optional
      description: "Brand introduction video",
      category: "marketing"
    }
  }),
});

const formData = new FormData();
formData.append("file", videoFile); // File object
formData.append("name", "brand-intro.mp4"); // optional

await fetch("https://api.orshot.com/v1/brand-assets/videos/add", {
method: "POST",
headers: {
Authorization: "Bearer <ORSHOT_API_KEY>",
},
body: formData,
});

{
  "data": {
    "video": {
      "id": 790,
      "created_at": "2025-09-11T10:15:30.123Z",
      "name": "brand-intro.mp4",
      "original_filename": "brand-intro.mp4",
      "file_size": 5242880,
      "direct_url": "https://storage.orshot.com/cloud/w-50/renders/videos/brand-intromp4-Qz5Rj7Fd1Ks.mp4",
      "width": 1920,
      "height": 1080,
      "duration": 30.5,
      "format": "mp4",
      "mime_type": "video/mp4",
      "thumbnail_url": null,
      "metadata": {
        "description": "Brand introduction video",
        "category": "marketing"
      },
      "tags": ["intro", "brand"],
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    },
    "url": "https://storage.orshot.com/cloud/w-50/renders/videos/brand-intromp4-Qz5Rj7Fd1Ks.mp4"
  }
}

Request Parameters#

Supported Video Formats#

• MP4 (video/mp4)
• WebM (video/webm)
• QuickTime / MOV (video/quicktime)
• AVI (video/x-msvideo)
• Matroska / MKV (video/x-matroska)
• FLV (video/x-flv)
• WMV (video/x-ms-wmv)
• M4V (video/x-m4v)
• GIF (image/gif)

Notes#

• Maximum file size: 60MB (checked again after any conversion)
• MP4 and WebM files with H.264, VP8, VP9 or AV1 video are kept. MP4 files may be rewritten so they start playing sooner
• Other containers (MOV, AVI, MKV, FLV, WMV) are repackaged as MP4. Other codecs, such as HEVC/H.265, are converted to H.264 MP4. This can change the file extension of the stored video (e.g. .mov to .mp4)
• GIFs are kept as GIFs
• Orshot does not read the width, height or duration from the file. Pass them in metadata if you need them. Otherwise they are null
• direct_url and url point to the stored file. Treat these URLs as opaque.

Error responses#

Input problems return 400 with a plain-language error and, for the two cases agents hit most, a stable code:

• VIDEO_NOT_A_VIDEO: the bytes carry no MP4, WebM, MOV, AVI, MKV, FLV, WMV, M4V or GIF signature. Usually a filename, a description, or placeholder text was sent instead of the file, or a URL served an HTML page.
• VIDEO_DATA_INCOMPLETE: the data starts as a real video file but ends early. The base64 was cut off in transit, the URL served a partial file, or the upload stopped before the end. The error names the fix for how the file was sent.

If the file URL cannot be downloaded, the request fails with 500:

{
  "error": "Failed to upload video"
}

Hosted chat clients such as ChatGPT and Claude.ai cannot send file bytes, so a base64 file from them is almost always cut off. Pass a publicly reachable video URL instead.

Query Parameters#

Per-User Libraries#

Pass embedId and embedUserId together to add the video to that embed user's private library instead of the shared workspace library. This is how one embed serves many brands or tenants, each with its own brand space.

Omit them and this endpoint behaves exactly as documented above. See Per-User Brand Assets for the full picture.

Rate Limits#

• 30 requests per minute per endpoint