Start (or resume) a multipart upload

POST/v1/videos/{id}/upload/start

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. 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), storage_quota_exceeded (402 — Free-plan projects at/over their storage quota; delete videos or upgrade to continue uploading).

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.

Parameters

Name	In	Type	Required	Description
`id`	path	string (Ulid)	Yes	—

Request body

required

Content type: application/json

Schema: UploadStartRequest

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

Responses

Status	Meaning
`201`	Upload session ready; `PUT` parts to `uploadUrlTemplate`.
`400`	The request body or query failed validation. The per-operation description lists the exact `error.code` values.
`401`	No valid credential was presented.
`403`	The credential is valid but does not permit this action. The per-operation description lists the exact `error.code` values.
`404`	The resource does not exist or is not visible to this caller.
`429`	Rate limit exceeded.

Example request

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

Try it

POST

/v1/videos/{id}/upload/start

Test mode only

API playground

Send a live request to api.videohati.com with a test-mode key.

This playground blocks vh_live_ keys. Use a key that starts with vh_test_ only; a request with a live key never leaves your browser.

Test-mode API key

The key is stored in your browser on docs.videohati.com only.

Request body (JSON)