Start (or resume) a multipart upload

This operation supports dashboard session-cookie authentication. Call it only from trusted server code; browsers must not manufacture or expose the session cookie.

Step 2 of the upload flow. Declares the file size and content type and returns an uploadUrlTemplate — replace {partNumber} (1-based) and PUT each part of partSize bytes (the final part is allowed to be shorter) to the upload endpoint. Calling start again with the same idempotencyKey resumes the existing session. Requires an API key with write scope, or session-cookie auth plus projectId. Rate limit: 60 requests per 60 s per caller.

Error codes: unauthorized (401), insufficient_scope (403), account_not_approved (403), invalid_project_id (400), not_found (404), video_not_found (404), invalid_size (400), invalid_checksum_sha256 (400), file_too_large (400), upload_limit_exceeded (429), insufficient_balance (402 — account effective balance under the −$2 floor; top up to continue), storage_quota_exceeded (402 — Trial projects at/over the 25 GB storage cap), encoding_quota_exceeded (402 — Trial projects past the 60 bundled encoding minutes).

Authentication

• apiKey — Project API key: Authorization: Bearer vh_live_... (live mode) or Authorization: Bearer vh_test_... (test mode). Keys carry read and/or write scopes.
• sessionCookie — Dashboard session cookie set by POST /v1/auth/login. Video and playback endpoints additionally require the projectId query parameter under cookie auth.

Parameters

Request body

required

Content type: application/json

Schema: UploadStartRequest

{
  "sizeBytes": 10485760,
  "contentType": "video/mp4",
  "idempotencyKey": "lecture-01-v1"
}

Responses

Example request

{
  "sizeBytes": 10485760,
  "contentType": "video/mp4",
  "idempotencyKey": "lecture-01-v1"
}

Try it