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/videos/workspace_id/brand-intro.mp4",
      "width": 1920,
      "height": 1080,
      "duration": 30.5,
      "format": "mp4",
      "mime_type": "video/mp4",
      "thumbnail_url": null,
      "metadata": {
        "description": "Brand introduction video",
        "category": "marketing"
      },
      "workspace_id": 50,
      "user_id": "abcdef01-2345-6789-abcd-ef0123456789"
    },
    "url": "https://storage.orshot.com/videos/workspace_id/brand-intro.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)
• Videos with web-compatible codecs (H.264) are stored as-is. Videos using codecs browsers can't play (e.g. HEVC/H.265) are automatically converted to H.264, which can change the file extension of the stored video (e.g. .mov to .mp4)

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.

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