POST/api/client/v1/uploads/video/initiate

What this API does

This endpoint performs a pre-upload step:

Validates video metadata
Checks subscription & quota eligibility
Generates a time-bound signed storage upload URL
Returns the final storage path for the uploaded video

Authentication

API credentials must be generated from:

https://buildvr.gretxp.com/profile/api-credentials

Headers

X-Client-ID: <YOUR_CLIENT_ID>
X-Client-Secret: <YOUR_CLIENT_SECRET>

Request Body

Field	Type	Required	Description
filename	string	Yes	Name of the video file (e.g. demo.mp4)
content_type	string	No	MIME type of the video (default: video/mp4)
expected_size_bytes	integer	No	Expected file size in bytes (used for quota validation)
expected_duration_sec	number	Yes	Expected video duration in seconds

JSON

{
  "filename": "intro.mp4",
  "content_type": "video/mp4",
  "expected_size_bytes": 52428800,
  "expected_duration_sec": 120
}

Subscription & Quota Validation

Before generating the upload URL, the system validates whether the upload is allowed based on your subscription plan.

Video duration limits
File size limits
Monthly / daily upload quotas
Plan-specific restrictions

If the upload exceeds your plan limits, the API will return a 403 Forbidden response with an explanatory message.

Response

On success, the API returns a signed upload URL along with the final storage path of the video.

200 OK

{
  "success": true,
  "upload_url": "https://storage.googleapis.com/...",
  "bucket_video_file": "users/42/uploads/intro.mp4",
  "expiration_hours": 6,
  "max_video_duration_sec": 2700
}

Important Upload Instructions:

The upload_url is time-bound and will expire after the number of hours specified in expiration_hours.
To perform the upload, you must send the file via a PUT request directly to the upload_url.
Once the upload is finished, call the Complete Upload endpoint to register the file and start processing.

Possible Errors

400 – filename or expected_duration_sec missing
401 – Upload not allowed for your subscription
403 – Invalid API credentials
500 – Unable to generate upload link

👉 Next: Complete Upload – confirm the upload and trigger processing.