Create a video in `uploading` state
Create a video in `uploading` state
/v1/videosThis operation supports dashboard session-cookie authentication. Call it only from trusted server code; browsers must not manufacture or expose the session cookie.
Step 1 of the upload flow. Requires an API key with write scope, or
session-cookie auth plus the projectId query parameter. Rate limit:
60 requests per 60 s per caller.
Send idempotencyKey to make creation safe to retry: a repeat of a
call that committed but lost its response returns the same videoId
rather than creating a second video. The key is FIRST-WRITE-WINS — see
the field description before reusing one.
Error codes: unauthorized (401), insufficient_scope (403),
account_not_approved (403), invalid_project_id (400),
not_found (404), invalid_filename (400), invalid_body (400),
video_create_conflict (409).
Authentication
- apiKey — Project API key:
Authorization: Bearer vh_live_...(live mode) orAuthorization: Bearer vh_test_...(test mode). Keys carryreadand/orwritescopes. - sessionCookie — Dashboard session cookie set by
POST /v1/auth/login. Video and playback endpoints additionally require theprojectIdquery parameter under cookie auth.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | query | string (Ulid) | No | Required when authenticating with the session cookie; ignored under API-key auth (the key is already project-scoped). |
Request body
required
Content type: application/json
Schema: VideoCreateRequest
{
"originalFilename": "lecture-01.mp4",
"idempotencyKey": "0f9a1c2e-6b7d-4a53-9d31-2b8f4c7a1e05"
}Responses
| Status | Meaning |
|---|---|
201 | Video created; continue with POST /v1/videos/{id}/upload/start. |
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. |
409 | video_create_conflict — an idempotencyKey that another create request holds could not be resolved to its video. Rare and transient; retry the identical request, which is safe by construction. |
429 | Rate limit exceeded. |
Example request
{
"originalFilename": "lecture-01.mp4",
"idempotencyKey": "0f9a1c2e-6b7d-4a53-9d31-2b8f4c7a1e05"
}Try it
/v1/videosAPI playground
Send a live request to api.videohati.com with a test-mode key.
The key is stored in your browser on docs.videohati.com only.
Required when authenticating with the session cookie; ignored under API-key auth (the key is already project-scoped).
https://api.videohati.com/v1/videos