<!-- Markdown twin of https://pixelvault.dev/docs/api/videos/ -->

[API reference](/docs/api/)

# Videos

Host original MP4 files byte-for-byte with a seekable CDN URL and a poster frame. Optional jobs create a social-ready H.264/AAC copy, a transcript and a storyboard. Files over 100 MB use the multipart upload session endpoints.

-   [The Video object](#object)
-   GET [List hosted videos](#list_videos)
-   POST [Upload or import an original MP4](#upload_video)
-   GET [Get video metadata](#get_video)
-   PATCH [Replace video organization fields](#update_video)
-   DELETE [Delete a video](#delete_video)
-   POST [Create a social-ready H.264/AAC fast-start MP4](#optimize_video)
-   POST [Generate a transcript and storyboard](#enrich_video)
-   POST [Analyze video metadata and social compatibility](#analyze_video)
-   POST [Generate or return a video's poster frame](#generate_video_poster)
-   POST [Create signed URLs for a video and its derivatives](#sign_video_url)
-   POST [Create a multipart MP4 upload](#create_video_upload)
-   PUT [Upload the next MP4 part](#upload_video_part)
-   POST [Complete and validate an MP4 upload](#complete_video_upload)
-   DELETE [Abort a multipart upload](#abort_video_upload)

## The Video object

A hosted original MP4. The bytes are stored as uploaded; PixelVault reads bounded container metadata and adds a poster frame. Derived files (poster, social-ready copy, transcript, storyboard) inherit the video's visibility and count toward the storage quota.

### Properties

The Video object properties

Property

Type

Description

`id`

string

Video id (`vid_` prefix).

`kind`

string

`url`

string (uri)

Seekable CDN URL of the original (supports `HEAD` and one `Range: bytes=…` per request). Signed for private videos.

`original_url`

string (uri)

The stored original MP4. Equal to `url`; explicit so one-step social-ready callers can retain both outputs.

`branded_url`

string (uri)

The original served from the project's active custom domain. Present only when a ready custom domain exists; signed query parameters are preserved.

`social_ready_url`

string (uri)

Completed H.264/AAC fast-start copy. Present only after social optimization completes with a derived copy.

`poster_url`

string (uri)

Generated 640×360 JPEG frame. Omitted until frame extraction succeeds (retry with [`generate_video_poster`](/docs/api/videos/#generate_video_poster)). Private videos return an expiry-matched signed poster URL.

`visibility`

string

Private videos are served only through signed URLs.

One of: `public`, `private`

`mime_type`

string

`size`

integer

Original size in bytes.

`width`

integer nullable

`height`

integer nullable

`duration_seconds`

number nullable

`video_codec`

string nullable

`audio_codec`

string nullable

`has_audio`

boolean nullable

`fast_start`

boolean nullable

Whether the `moov` atom precedes media data for progressive playback.

`social_compatible`

boolean nullable

True for an H.264 MP4 with AAC or no audio, readable dimensions and duration, and fast-start layout. Other valid MP4s still upload unchanged. Null for legacy videos not yet analyzed ([`analyze_video`](/docs/api/videos/#analyze_video)).

`compatibility_warnings`

array of object

What to fix before sending the URL to a social publishing tool. Empty when `social_compatible` is true.

Child properties of `compatibility_warnings`

Properties of compatibility\_warnings

Property

Type

Description

`code`

string

One of: `video_codec_not_h264`, `video_codec_unknown`, `audio_codec_not_aac`, `audio_codec_unknown`, `not_fast_start`, `fast_start_unknown`, `dimensions_unknown`, `duration_unknown`

`message`

string

`social_optimization`

VideoSocialOptimization

State of the optional social preset. The original MP4 is never replaced. not\_needed means the original already passed H.264/AAC fast-start validation.

Child properties of `social_optimization`

Properties of social\_optimization

Property

Type

Description

`preset`

string

`status`

string

Poll [`get_video`](/docs/api/videos/#get_video) while `pending` or `processing`. `not_needed`: the original already passes, and `url` is the original.

One of: `not_requested`, `pending`, `processing`, `complete`, `failed`, `not_needed`

`source`

string

`derived` for a separate optimized copy, `original` when the original is already social-ready.

One of: `original`, `derived`

`url`

string (uri)

The social-ready MP4 (signed for private videos). Present when status is `complete` or `not_needed`.

`size`

integer nullable

Bytes of the social-ready file.

`duration_seconds`

number nullable

`video_codec`

string nullable

`audio_codec`

string nullable

`fast_start`

boolean nullable

`requested_at`

string (date-time)

`completed_at`

string (date-time) nullable

`error`

object

Present when status is `failed`. Retry with [`optimize_video`](/docs/api/videos/#optimize_video); failed jobs return their reserved monthly seconds.

Child properties of `error`

Properties of error

Property

Type

Description

`code`

string

`message`

string

`enrichment`

VideoEnrichment

State of the optional transcript + storyboard job. Generated artifacts inherit the video's visibility and signed-URL expiry.

Child properties of `enrichment`

Properties of enrichment

Property

Type

Description

`status`

string

Poll [`get_video`](/docs/api/videos/#get_video) until `complete` or `failed`.

One of: `not_requested`, `pending`, `processing`, `complete`, `failed`

`job_id`

string

Stable identifier for this enrichment attempt. Repeated requests while queued, running, or complete return the same job ID; retrying a failed job creates a new one.

`requested_at`

string (date-time)

`completed_at`

string (date-time) nullable

`transcript`

object

Transcript artifacts. `skipped` with `reason: no_audio` for a silent video (the storyboard is still produced).

Child properties of `transcript`

Properties of transcript

Property

Type

Description

`status`

string

One of: `complete`, `skipped`

`text_url`

string (uri)

Plain-text transcript.

`vtt_url`

string (uri)

Timed WebVTT captions.

`segments_url`

string (uri)

Timestamped JSON segments.

`language`

string nullable

Primary detected language.

`languages`

array of string

`model`

string nullable

`segment_count`

integer

`reason`

string

Why the transcript was skipped.

One of: `no_audio`

`storyboard`

object nullable

Storyboard index plus bounded JPEG contact sheets of sampled frames.

Child properties of `storyboard`

Properties of storyboard

Property

Type

Description

`status`

string

`index_url`

string (uri)

JSON index of the sampled frames and sheets.

`frame_count`

integer

`sheets`

array of object

Child properties of `sheets`

Properties of sheets

Property

Type

Description

`url`

string (uri)

`start_seconds`

number

`end_seconds`

number

`frame_count`

integer

`error`

object

Present when status is `failed`. Call [`enrich_video`](/docs/api/videos/#enrich_video) again to retry with a new `job_id`.

Child properties of `error`

Properties of error

Property

Type

Description

`code`

string

`message`

string

`filename`

string

`folder`

string nullable

Logical folder used for organization and list filtering.

`collection_id`

string nullable

Collection membership; the collection's visibility matches the video's.

`metadata`

object nullable

Caller-managed custom metadata (max 50 top-level keys, 4 KB).

`created_at`

string (date-time)

`expires_at`

string (date-time)

Deletion time for a temporary video (`expires_in`). The hourly sweep can lag by about two hours; it fails active jobs, returns their reserved seconds, and deletes the original and every derivative. Signed-URL expiry is separate.

`temporary`

boolean

Present and true only when `expires_at` is set.

`replayed`

boolean

Present and true when an idempotent retry returns an existing video.

`signed_expires`

integer

Unix timestamp when private original and derivative bearer URLs expire. Private videos only.

The Video object

```
{
  "id": "vid_abc123",
  "kind": "video",
  "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
  "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
  "branded_url": "https://media.example.com/vid_abc123.mp4",
  "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
  "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
  "visibility": "public",
  "mime_type": "video/mp4",
  "size": 24000000,
  "width": 1920,
  "height": 1080,
  "duration_seconds": 42.417,
  "video_codec": "h264",
  "audio_codec": "aac",
  "has_audio": true,
  "fast_start": true,
  "social_compatible": true,
  "compatibility_warnings": [],
  "social_optimization": {
    "preset": "social",
    "status": "complete",
    "source": "derived",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "size": 18400000,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "fast_start": true,
    "requested_at": "2026-11-16T12:00:00.000Z",
    "completed_at": "2026-11-16T12:01:10.000Z",
    "error": {
      "code": "optimization_failed",
      "message": "The video could not be optimized."
    }
  },
  "enrichment": {
    "status": "complete",
    "job_id": "ven_abc123",
    "requested_at": "2026-11-16T12:00:00.000Z",
    "completed_at": "2026-11-16T12:02:30.000Z",
    "transcript": {
      "status": "complete",
      "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
      "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
      "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
      "language": "en",
      "languages": [
        "en"
      ],
      "model": "@cf/openai/whisper-large-v3-turbo",
      "segment_count": 18
    },
    "storyboard": {
      "status": "complete",
      "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
      "frame_count": 16,
      "sheets": [
        {
          "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
          "start_seconds": 0,
          "end_seconds": 42.417,
          "frame_count": 16
        }
      ]
    },
    "error": {
      "code": "transcription_failed",
      "message": "The video could not be transcribed."
    }
  },
  "filename": "launch-demo.mp4",
  "folder": "agents",
  "collection_id": "col_abc123",
  "metadata": {
    "run": "42"
  },
  "created_at": "2026-11-16T12:00:00.000Z",
  "expires_at": "2026-11-17T12:00:00.000Z",
  "temporary": true,
  "replayed": true,
  "signed_expires": 1795449600
}
```

## List hosted videos

GET `/v1/videos`

A page of the project's videos, newest first, with folder, collection and custom-metadata filters (combined with AND). Private videos carry fresh signed URLs (1 hour).

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Query parameters

Query parameters

Name

Type

Required

Description

`page`

integer

Optional

Page number, from 1.

Default: `1`

min 1

`per_page`

integer

Optional

Videos per page (max 100).

Default: `20`

min 1 · max 100

`collection_id`

string

Optional

Only videos in this collection.

`folder`

string

Optional

Exact logical-folder match.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`metadata`

string

Optional

JSON object; returns videos whose custom metadata contains every key/value pair.

`meta[key]`

string

Optional

Shorthand string match on one metadata key, e.g. `?meta[run]=42`; combines with `metadata`.

### Responses

-   200
    
    Paginated videos
    
-   400
    
    [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name. [`validation_error`](/docs/errors/#validation_error): malformed or conflicting metadata filter.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl "https://api.pixelvault.dev/v1/videos?per_page=20" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": [
    {
      "id": "vid_abc123",
      "kind": "video",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
      "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
      "branded_url": "https://media.example.com/vid_abc123.mp4",
      "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
      "visibility": "public",
      "mime_type": "video/mp4",
      "size": 24000000,
      "width": 1920,
      "height": 1080,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "has_audio": true,
      "fast_start": true,
      "social_compatible": true,
      "compatibility_warnings": [],
      "social_optimization": {
        "preset": "social",
        "status": "complete",
        "source": "derived",
        "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
        "size": 18400000,
        "duration_seconds": 42.417,
        "video_codec": "h264",
        "audio_codec": "aac",
        "fast_start": true,
        "requested_at": "2026-11-16T12:00:00.000Z",
        "completed_at": "2026-11-16T12:01:10.000Z",
        "error": {
          "code": "optimization_failed",
          "message": "The video could not be optimized."
        }
      },
      "enrichment": {
        "status": "complete",
        "job_id": "ven_abc123",
        "requested_at": "2026-11-16T12:00:00.000Z",
        "completed_at": "2026-11-16T12:02:30.000Z",
        "transcript": {
          "status": "complete",
          "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
          "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
          "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
          "language": "en",
          "languages": [
            "en"
          ],
          "model": "@cf/openai/whisper-large-v3-turbo",
          "segment_count": 18
        },
        "storyboard": {
          "status": "complete",
          "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
          "frame_count": 16,
          "sheets": [
            {}
          ]
        },
        "error": {
          "code": "transcription_failed",
          "message": "The video could not be transcribed."
        }
      },
      "filename": "launch-demo.mp4",
      "folder": "agents",
      "collection_id": "col_abc123",
      "metadata": {
        "run": "42"
      },
      "created_at": "2026-11-16T12:00:00.000Z",
      "expires_at": "2026-11-17T12:00:00.000Z",
      "temporary": true,
      "replayed": true,
      "signed_expires": 1795449600
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}
```

## Upload or import an original MP4

POST `/v1/videos`

Upload original MP4 bytes, or import an https URL, and get a seekable CDN URL plus a generated 640×360 JPEG poster when frame extraction succeeds. PixelVault stores the bytes as provided and reads bounded container metadata for duration, dimensions, codecs and fast-start layout. Requires a secret API key or dashboard session and a verified email.

Plan limits:

-   Free: MP4s up to 25 MB; 2 minutes of social-ready output and 2 source minutes of transcript + storyboard a month
-   Starter: up to 100 MB; 30 and 30 minutes
-   Pro: up to 250 MB; 120 and 120 minutes

Videos, posters, optimized copies, transcripts and storyboard sheets consume the same storage, upload-count and bandwidth quotas as images. The CDN supports `HEAD` and single `Range: bytes=…` requests for seeking.

**Direct upload:** send `Content-Type: video/mp4`, `Content-Length` and optional `X-PixelVault-*` headers. Direct uploads stop at 100 MB; use [`create_video_upload`](/docs/api/videos/#create_video_upload) for larger files.

**Import by URL:** send `application/json` with an https `url`. The remote server must return `Content-Length`; PixelVault streams the response directly to storage (5-minute timeout), checks the size and MP4 signature, and allows the full plan limit without multipart.

**Social-ready:** `X-PixelVault-Social-Ready: true` (or `social_ready` for URL imports) enqueues a separate H.264/AAC fast-start copy in the same request; the original is never changed. The response returns immediately: poll [`get_video`](/docs/api/videos/#get_video) while `social_optimization.status` is `pending` or `processing`. If the job cannot start (for example the monthly allowance is used), the upload still succeeds and `social_optimization` reports `failed` with the reason. `social_compatible` is true when the file uses H.264 video, AAC or no audio, has readable dimensions and duration, and places its `moov` atom before media data; other valid MP4s still upload unchanged and `compatibility_warnings` explains what to fix. CLI: `pixelvault upload launch-demo.mp4 --social` waits and prints the post-ready URL.

**Retry-safe uploads:** `Idempotency-Key` (up to 255 non-space printable ASCII characters) is scoped to the project and retained for 24 hours. An exact retry returns the committed asset (200, `replayed: true`) without storing or billing another copy; conflicting URL, bytes, visibility, TTL, metadata, folder or collection inputs return 422 [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse); a retry while the first request is still running returns 409 [`idempotency_in_progress`](/docs/errors/#idempotency_in_progress). A direct upload with a key must also send `X-PixelVault-Content-SHA256`, verified while streaming; URL imports fingerprint the source URL and storage settings before fetching. This is request idempotency, not content deduplication: different keys create distinct assets, and content is never deduplicated across owners or privacy boundaries.

**Lifecycle and organization:** `expires_in` (60–2,592,000 seconds) deletes the original, poster, optimized copy, transcripts and storyboards; active optimization or enrichment jobs are failed and their reserved quota returned. The hourly sweep can lag by about two hours. `sign_expires_in` only expires bearer URLs and never deletes bytes. Set `folder`, an existing same-visibility `collection_id` and custom `metadata` at upload, replace them with [`update_video`](/docs/api/videos/#update_video), and filter with [`list_videos`](/docs/api/videos/#list_videos). Private videos (free plan: 100 private assets) return signed video and poster URLs.

Prefer a browser? The [Video to URL tool](https://pixelvault.dev/tools/video-to-url/) accepts MP4s up to 25 MB with no signup and returns a 24-hour URL that can be claimed into a free account. A new video emits `media.created`.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Headers

Headers

Name

Type

Required

Description

`X-PixelVault-Filename`

string

Optional

Direct uploads: original filename, 1–255 UTF-8 bytes. Percent-encode non-ASCII characters. Defaults to `video.mp4`.

max length 255

`X-PixelVault-Visibility`

string

Optional

Direct uploads: `private` returns signed video and poster URLs.

One of: `public`, `private`

Default: `public`

`X-PixelVault-Sign-Expires-In`

integer

Optional

Direct uploads: lifetime in seconds of the returned private video and poster URLs. Never deletes the video.

Default: `3600`

min 60 · max 2592000

`X-PixelVault-Social-Ready`

boolean

Optional

Direct uploads: `true` enqueues a separate H.264/AAC fast-start copy while preserving the original.

Default: `false`

`Idempotency-Key`

string

Optional

Up to 255 non-space printable ASCII characters; replays for 24 hours within this project. Conflicting inputs return 422 [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse).

max length 255 · pattern ^\[\\x21-\\x7e\]+$

`X-PixelVault-Content-SHA256`

string

Optional

Hex SHA-256 of the MP4 bytes, verified while streaming. Required with `Idempotency-Key` for a direct upload.

pattern ^\[a-fA-F0-9\]{64}$

`X-PixelVault-Folder`

string

Optional

Direct uploads: logical folder (letters, numbers, hyphens, underscores; max 64).

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`X-PixelVault-Collection-Id`

string

Optional

Direct uploads: an existing collection with the same visibility.

`X-PixelVault-Metadata`

string

Optional

Direct uploads: custom metadata as a JSON object string (max 50 keys, 4 KB).

`X-PixelVault-Expires-In`

integer

Optional

Direct uploads: delete the video and every derivative after this many seconds.

min 60 · max 2592000

### Request body (application/json)

`application/json`, required

Request body (application/json)

Name

Type

Required

Description

`url`

string (uri)

Required

Public https URL of the MP4. Must return `Content-Length`.

`filename`

string

Optional

Original filename; defaults to the URL's last path segment.

max length 255

`visibility`

string

Optional

One of: `public`, `private`

Default: `public`

`sign_expires_in`

integer

Optional

Lifetime in seconds of the returned private URLs.

Default: `3600`

min 60 · max 2592000

`social_ready`

boolean

Optional

Enqueue a separate social-ready copy while preserving the original. Sources must be at most 100 MB and 60 seconds.

Default: `false`

`folder`

string

Optional

Logical folder.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`collection_id`

string

Optional

An existing collection with the same visibility.

`metadata`

object

Optional

Custom metadata (max 50 keys, 4 KB).

`expires_in`

integer

Optional

Deletion TTL in seconds; distinct from `sign_expires_in`.

min 60 · max 2592000

### Request body (raw bytes)

The file bytes as the request body, with `Content-Type` set to `video/mp4`.

### Responses

-   200
    
    Idempotent replay of an existing video (`replayed: true`)
    
-   201
    
    Video hosted
    
-   400
    
    [`invalid_file`](/docs/errors/#invalid_file): not an MP4 container, or under 16 bytes. [`missing_file`](/docs/errors/#missing_file): empty body. [`checksum_mismatch`](/docs/errors/#checksum_mismatch): the bytes do not match `X-PixelVault-Content-SHA256`. [`idempotency_checksum_required`](/docs/errors/#idempotency_checksum_required): a direct upload with `Idempotency-Key` needs the checksum header. [`invalid_json`](/docs/errors/#invalid_json) / [`missing_url`](/docs/errors/#missing_url): bad URL-import body. [`url_length_required`](/docs/errors/#url_length_required): the remote server sent no valid `Content-Length`. [`invalid_url`](/docs/errors/#invalid_url), [`unsupported_scheme`](/docs/errors/#unsupported_scheme), [`blocked_host`](/docs/errors/#blocked_host), [`url_fetch_failed`](/docs/errors/#url_fetch_failed): the URL could not be imported. [`invalid_upload`](/docs/errors/#invalid_upload): the stored upload was incomplete. [`invalid_folder`](/docs/errors/#invalid_folder), [`validation_error`](/docs/errors/#validation_error): a bad header or field (filename, visibility, `sign_expires_in`, social-ready flag, metadata, `expires_in`, `collection_id` or `Idempotency-Key`).
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached), [`private_limit_reached`](/docs/errors/#private_limit_reached): a plan quota is full.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`collection_not_found`](/docs/errors/#collection_not_found): no such collection in the project. `no_project`: the signed-in account has no project.
    
-   409
    
    [`idempotency_in_progress`](/docs/errors/#idempotency_in_progress): an upload with this `Idempotency-Key` is still running; the error also carries `upload_id`, `asset_id` and `expires_at`. Retry later.
    
-   410
    
    [`idempotency_result_deleted`](/docs/errors/#idempotency_result_deleted): the video created with this `Idempotency-Key` was deleted; use a new key.
    
-   411
    
    [`length_required`](/docs/errors/#length_required): a direct upload needs a valid `Content-Length`.
    
-   413
    
    [`multipart_required`](/docs/errors/#multipart_required): direct uploads over 100 MB must use [`create_video_upload`](/docs/api/videos/#create_video_upload). [`file_too_large`](/docs/errors/#file_too_large): larger than the plan's video limit (25 MB Free, 100 MB Starter, 250 MB Pro). [`url_too_large`](/docs/errors/#url_too_large): the remote file exceeds the plan limit. [`optimization_source_too_large`](/docs/errors/#optimization_source_too_large): `social_ready` with a source over 100 MB.
    
-   415
    
    [`unsupported_media_type`](/docs/errors/#unsupported_media_type): `Content-Type` must be `video/mp4` or `application/json`.
    
-   422
    
    [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse): the `Idempotency-Key` was already used with different URL, bytes, visibility, TTL, metadata, folder or collection inputs. [`collection_visibility_mismatch`](/docs/errors/#collection_visibility_mismatch): the collection's visibility differs from the video's.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "X-PixelVault-Filename: launch-demo.mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @launch-demo.mp4
```

Response 201

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Get video metadata

GET `/v1/videos/{id}`

One video: original metadata, social-ready and enrichment job state with their artifact URLs, and organization fields. Poll this while `social_optimization.status` or `enrichment.status` is `pending` or `processing`. Private videos return fresh expiry-matched signed URLs (1 hour) for the original and every existing derivative.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Video metadata
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/videos/vid_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Replace video organization fields

PATCH `/v1/videos/{id}`

Replace custom metadata, logical folder and/or collection membership. Send at least one field; omitted fields remain unchanged and `null` clears. The collection's visibility must match the video's. The request body may be at most 16 KB.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`metadata`

object nullable

Optional

Replaces the stored metadata (not merged).

`folder`

string nullable

Optional

New logical folder.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`collection_id`

string nullable

Optional

An existing collection with the same visibility.

### Responses

-   200
    
    Updated video
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): the body is not JSON, has none of `metadata`, `folder`, `collection_id`, or a value is invalid. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. [`collection_not_found`](/docs/errors/#collection_not_found): no such collection. `no_project`: the signed-in account has no project.
    
-   413
    
    [`payload_too_large`](/docs/errors/#payload_too_large): the request body is larger than 16 KB.
    
-   422
    
    [`collection_visibility_mismatch`](/docs/errors/#collection_visibility_mismatch): the collection's visibility differs from the video's.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X PATCH https://api.pixelvault.dev/v1/videos/vid_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"run":"43"},"folder":"agents"}'
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Delete a video

DELETE `/v1/videos/{id}`

Permanently delete a video: the original, poster, social-ready copy, transcripts, storyboard and the record are removed and their storage freed; signed URLs stop working. Active optimization or enrichment jobs are failed and their reserved seconds returned. Emits `media.deleted`. To cancel an unfinished multipart upload use [`abort_video_upload`](/docs/api/videos/#abort_video_upload) instead.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Deleted
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X DELETE https://api.pixelvault.dev/v1/videos/vid_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "success": true
}
```

## Create a social-ready H.264/AAC fast-start MP4

POST `/v1/videos/{id}/optimize`

Create, or retry, a separate social-ready H.264/AAC fast-start copy of an existing video; the original is never changed. Idempotent: returns 202 while queued or processing, 200 when complete, and 200 without creating a copy when the original is already compatible (`status: not_needed`). Poll [`get_video`](/docs/api/videos/#get_video) until `social_optimization.status` is `complete` or `failed`. Failed jobs return their reserved monthly seconds; emits `video.optimization.completed` or `video.optimization.failed`.

Sources up to 100 MB and 60 seconds on every plan. Monthly output allowance: 2 minutes Free, 30 minutes Starter, 120 minutes Pro ([`get_usage`](/docs/api/usage/#get_usage) → `video_optimization`). The optimized copy uses storage quota.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Already complete, or the original is already social-ready
    
-   202
    
    Optimization queued or processing
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`optimization_limit_reached`](/docs/errors/#optimization_limit_reached): the monthly social-ready allowance cannot cover this duration.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   413
    
    [`optimization_source_too_large`](/docs/errors/#optimization_source_too_large): the source exceeds 100 MB.
    
-   422
    
    [`video_metadata_unavailable`](/docs/errors/#video_metadata_unavailable): the MP4 metadata could not be read. [`video_duration_unavailable`](/docs/errors/#video_duration_unavailable): the duration is unknown. [`optimization_duration_too_long`](/docs/errors/#optimization_duration_too_long): longer than 60 seconds.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    
-   503
    
    [`optimization_unavailable`](/docs/errors/#optimization_unavailable): optimization is temporarily unavailable; nothing was charged.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/optimize \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Generate a transcript and storyboard

POST `/v1/videos/{id}/enrich`

Generate plain-text, timed WebVTT and timestamped JSON transcripts plus a storyboard index and bounded JPEG sheets for an owned video. Idempotent: returns 202 while queued or processing and 200 when complete; `enrichment.job_id` identifies the stable attempt, and retrying a failed job creates a new job id. Poll [`get_video`](/docs/api/videos/#get_video) until `enrichment.status` is `complete` or `failed`. Videos without audio skip only the transcript. Private videos get expiry-matched signed URLs for every artifact. Emits `video.enrichment.completed` or `video.enrichment.failed`.

Sources must be 1 second through 10 minutes and at most 100 MB. Monthly source-minute allowance, shared with audio transcription: 2 Free, 30 Starter, 120 Pro ([`get_usage`](/docs/api/usage/#get_usage) → `video_enrichment`); the remaining allowance must cover the full source duration. Generated artifact bytes use storage quota.

CLI 0.23.0+ wraps the workflow: `pixelvault enrich-video ./launch-demo.mp4 --json` uploads and enriches, `pixelvault enrich-video vid_abc123 --json` resumes an existing asset. It reports the asset and job ids before polling, backs off for up to 600 seconds by default (`--timeout`, `--no-wait`), and a local timeout does not cancel the server job.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Enrichment already complete
    
-   202
    
    Enrichment queued or processing
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`enrichment_limit_reached`](/docs/errors/#enrichment_limit_reached): the shared monthly media-enrichment allowance cannot cover this duration.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   413
    
    [`enrichment_source_too_large`](/docs/errors/#enrichment_source_too_large): the source exceeds 100 MB.
    
-   422
    
    [`video_metadata_unavailable`](/docs/errors/#video_metadata_unavailable): the MP4 metadata could not be read. [`video_duration_unavailable`](/docs/errors/#video_duration_unavailable): the duration is unknown, invalid or under 1 second. [`enrichment_duration_too_long`](/docs/errors/#enrichment_duration_too_long): longer than 10 minutes.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    
-   503
    
    [`enrichment_unavailable`](/docs/errors/#enrichment_unavailable): frame extraction or transcription is temporarily unavailable; nothing was charged.
    

Request

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/enrich \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Analyze video metadata and social compatibility

POST `/v1/videos/{id}/analyze`

Re-read bounded MP4 container metadata (dimensions, duration, codecs, fast-start layout) without transcoding and refresh `social_compatible` and `compatibility_warnings`. Use it to backfill legacy videos whose fields are null.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Analyzed video
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   422
    
    [`video_metadata_unavailable`](/docs/errors/#video_metadata_unavailable): the MP4 metadata could not be read.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/analyze \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Generate or return a video's poster frame

POST `/v1/videos/{id}/poster`

Extract and store a 640×360 JPEG poster frame, or return the video unchanged when it already has one. Use it to backfill legacy videos or retry a transient frame-extraction failure from upload. The poster uses storage quota.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Responses

-   200
    
    Video with `poster_url`
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   422
    
    [`poster_generation_failed`](/docs/errors/#poster_generation_failed): no frame could be extracted. [`poster_too_large`](/docs/errors/#poster_too_large): the extracted frame exceeds 2 MB.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    
-   503
    
    [`poster_unavailable`](/docs/errors/#poster_unavailable): frame extraction is temporarily unavailable; retry later.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/poster \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Create signed URLs for a video and its derivatives

POST `/v1/videos/{id}/sign-url`

Mint one expiry-matched set of bearer URLs for the original MP4 and every derivative that exists: poster, completed social-ready copy, transcript artifacts and storyboard sheets. Does not change visibility or deletion TTL. Use it when private links (including a webhook payload's) expire.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Video id.

### Request body

`application/json`, optional

Request body

Name

Type

Required

Description

`expires_in`

integer

Optional

Lifetime of every URL, in seconds.

Default: `3600`

min 60 · max 2592000

### Responses

-   200
    
    Expiry-matched signed URLs for every available artifact
    
-   400
    
    [`invalid_expires_in`](/docs/errors/#invalid_expires_in): `expires_in` is not an integer between 60 and 2592000.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`video_not_found`](/docs/errors/#video_not_found): no video with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/sign-url \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in":3600}'
```

Response 200

```
{
  "data": {
    "url": "https://img.pixelvault.dev/proj_xyz789/cp/v/vid_abc123.mp4?token=3f9a…&expires=1795449600",
    "branded_url": "https://media.example.com/cp/v/vid_abc123.mp4?token=3f9a…&expires=1795449600",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/cp/v/vid_abc123.poster.jpg?token=8b21…&expires=1795449600",
    "social_url": "https://img.pixelvault.dev/proj_xyz789/cp/v/vid_abc123.social.mp4?token=c7d0…&expires=1795449600",
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "expires": 1795449600
  }
}
```

## Create a multipart MP4 upload

POST `/v1/videos/uploads`

Start a multipart MP4 upload session: required for files over 100 MB, and usable for any size up to the plan's video limit (25 MB Free, 100 MB Starter, 250 MB Pro). Storage and upload quota are reserved now and released if the session is aborted or expires.

Flow:

-   [`create_video_upload`](/docs/api/videos/#create_video_upload) with the whole-file `size` (and `sha256` when using `Idempotency-Key`)
-   [`upload_video_part`](/docs/api/videos/#upload_video_part) for parts 1, 2, … in order, each `part_size` bytes except the last
-   [`complete_video_upload`](/docs/api/videos/#complete_video_upload) to validate and commit the video (signed-URL lifetime and social-ready flag are set there)
-   or [`abort_video_upload`](/docs/api/videos/#abort_video_upload) to cancel an active session

`Idempotency-Key` is project-scoped and retained for 24 hours: an exact retry returns the same active session (200, `replayed: true`) or, once completed, the committed video (`completed: true`, `asset`); conflicting inputs return 422 [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse). This retry contract is separate from content deduplication. Sessions expire after 24 hours.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Headers

Headers

Name

Type

Required

Description

`Idempotency-Key`

string

Optional

Up to 255 non-space printable ASCII characters; replays for 24 hours within this project. Requires `sha256`.

max length 255 · pattern ^\[\\x21-\\x7e\]+$

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`filename`

string

Required

Original filename, 1–255 UTF-8 bytes.

max length 255

`size`

integer

Required

Whole-file size in bytes.

min 16

`visibility`

string

Optional

One of: `public`, `private`

Default: `public`

`sha256`

string

Optional

Whole-file hex digest used to detect conflicting retries. Required with `Idempotency-Key`.

pattern ^\[a-fA-F0-9\]{64}$

`folder`

string

Optional

Logical folder.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`collection_id`

string

Optional

An existing collection with the same visibility.

`metadata`

object

Optional

Custom metadata (max 50 keys, 4 KB).

`expires_in`

integer

Optional

Deletion TTL of the completed video, in seconds.

min 60 · max 2592000

### Responses

-   200
    
    Idempotent replay of an active or completed session
    
-   201
    
    Multipart session created
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): missing or invalid `filename`, `size` (at least 16 bytes), `visibility`, `sha256`, `metadata`, `expires_in`, `collection_id` or `Idempotency-Key`. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name. [`idempotency_checksum_required`](/docs/errors/#idempotency_checksum_required): `Idempotency-Key` needs `sha256`.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached), [`private_limit_reached`](/docs/errors/#private_limit_reached): a plan quota is full.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`collection_not_found`](/docs/errors/#collection_not_found): no such collection in the project. `no_project`: the signed-in account has no project.
    
-   410
    
    [`idempotency_result_deleted`](/docs/errors/#idempotency_result_deleted): the video created with this `Idempotency-Key` was deleted; use a new key.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): `size` exceeds the plan's video limit.
    
-   422
    
    [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse): the `Idempotency-Key` was already used with different inputs. [`collection_visibility_mismatch`](/docs/errors/#collection_visibility_mismatch): the collection's visibility differs from the video's.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/uploads \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "clip.mp4",
  "size": 250000000,
  "visibility": "private",
  "folder": "agents",
  "metadata": {
    "run": "42"
  },
  "expires_in": 86400
}'
```

Response 201

```
{
  "data": {
    "upload_id": "vup_abc123",
    "asset_id": "vid_abc123",
    "part_size": 10485760,
    "size": 250000000,
    "visibility": "private",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "asset_expires_at": "2026-11-18T12:00:00.000Z",
    "replayed": true,
    "completed": true,
    "asset": {
      "id": "vid_abc123",
      "kind": "video",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
      "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
      "branded_url": "https://media.example.com/vid_abc123.mp4",
      "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
      "visibility": "public",
      "mime_type": "video/mp4",
      "size": 24000000,
      "width": 1920,
      "height": 1080,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "has_audio": true,
      "fast_start": true,
      "social_compatible": true,
      "compatibility_warnings": [],
      "social_optimization": {
        "preset": "social",
        "status": "complete",
        "source": "derived",
        "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
        "size": 18400000,
        "duration_seconds": 42.417,
        "video_codec": "h264",
        "audio_codec": "aac",
        "fast_start": true,
        "requested_at": "2026-11-16T12:00:00.000Z",
        "completed_at": "2026-11-16T12:01:10.000Z",
        "error": {
          "code": "optimization_failed",
          "message": "The video could not be optimized."
        }
      },
      "enrichment": {
        "status": "complete",
        "job_id": "ven_abc123",
        "requested_at": "2026-11-16T12:00:00.000Z",
        "completed_at": "2026-11-16T12:02:30.000Z",
        "transcript": {
          "status": "complete",
          "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
          "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
          "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
          "language": "en",
          "languages": [
            "en"
          ],
          "model": "@cf/openai/whisper-large-v3-turbo",
          "segment_count": 18
        },
        "storyboard": {
          "status": "complete",
          "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
          "frame_count": 16,
          "sheets": [
            {}
          ]
        },
        "error": {
          "code": "transcription_failed",
          "message": "The video could not be transcribed."
        }
      },
      "filename": "launch-demo.mp4",
      "folder": "agents",
      "collection_id": "col_abc123",
      "metadata": {
        "run": "42"
      },
      "created_at": "2026-11-16T12:00:00.000Z",
      "expires_at": "2026-11-17T12:00:00.000Z",
      "temporary": true,
      "replayed": true,
      "signed_expires": 1795449600
    }
  }
}
```

## Upload the next MP4 part

PUT `/v1/videos/uploads/{uploadId}/parts/{partNumber}`

Upload one raw part of a multipart session. Parts are sequential from 1; every non-final part must be exactly the session's `part_size`, each part at most 100 MB, and `Content-Length` is required. For sessions created with an `Idempotency-Key`, send `X-PixelVault-Part-SHA256`: an exact retry of a stored part returns it with `replayed: true`, while different bytes for an existing part return 409.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`uploadId`

string

Required

`upload_id` from [`create_video_upload`](/docs/api/videos/#create_video_upload).

`partNumber`

integer

Required

1-based part number; the next part expected is one more than the parts stored.

min 1

### Headers

Headers

Name

Type

Required

Description

`X-PixelVault-Part-SHA256`

string

Optional

Hex SHA-256 of this part, verified while streaming. Required when the session has an `Idempotency-Key`.

pattern ^\[a-fA-F0-9\]{64}$

### Request body

The file bytes as the request body, with `Content-Type` set to `application/octet-stream`.

### Responses

-   200
    
    Part stored (or an exact retry replayed)
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): bad part number, the part is out of order, or `Content-Length` is missing or over 100 MB. [`part_checksum_required`](/docs/errors/#part_checksum_required): the session has an `Idempotency-Key`, so `X-PixelVault-Part-SHA256` is required. [`checksum_mismatch`](/docs/errors/#checksum_mismatch): the bytes do not match the header.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`upload_not_found`](/docs/errors/#upload_not_found): no active or completed session with this id in the project (it may have expired).
    
-   409
    
    [`upload_complete`](/docs/errors/#upload_complete): the session is already complete. [`part_already_uploaded`](/docs/errors/#part_already_uploaded): that part exists with different or unverifiable bytes. [`concurrent_part_conflict`](/docs/errors/#concurrent_part_conflict): concurrent requests sent different bytes for the same part and the session was aborted; start a new upload.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): the parts would exceed the declared `size`.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X PUT https://api.pixelvault.dev/v1/videos/uploads/vup_abc123/parts/1 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @launch-demo.part1
```

Response 200

```
{
  "data": {
    "part_number": 1,
    "etag": "2b4e8f0c1d9a7e65",
    "received": 10485760,
    "replayed": true
  }
}
```

## Complete and validate an MP4 upload

POST `/v1/videos/uploads/{uploadId}/complete`

Assemble the parts, validate the MP4, and commit the video (with metadata analysis and a poster frame). Finalization is replay-safe: calling it again after a lost success response returns the committed video (200, `replayed: true`); replay markers remain for 24 hours. A video that fails validation is deleted and its reserved quota released.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`uploadId`

string

Required

`upload_id` from [`create_video_upload`](/docs/api/videos/#create_video_upload).

### Headers

Headers

Name

Type

Required

Description

`X-PixelVault-Sign-Expires-In`

integer

Optional

Lifetime in seconds of the returned private video and poster URLs.

Default: `3600`

min 60 · max 2592000

`X-PixelVault-Social-Ready`

boolean

Optional

`true` enqueues a social-ready copy after completion. Sources must be at most 100 MB and 60 seconds; otherwise the video still commits and `social_optimization` reports `failed`.

Default: `false`

### Responses

-   200
    
    Idempotent replay after a successful commit (`replayed: true`)
    
-   201
    
    Video hosted
    
-   400
    
    [`invalid_upload`](/docs/errors/#invalid_upload): parts are missing, out of order, do not add up to the declared size, or a non-final part differs from the others or is under 5 MiB. [`invalid_file`](/docs/errors/#invalid_file): the assembled bytes are not an MP4. [`validation_error`](/docs/errors/#validation_error): bad `X-PixelVault-Sign-Expires-In` or `X-PixelVault-Social-Ready`.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`upload_not_found`](/docs/errors/#upload_not_found): no session with this id in the project (it may have expired).
    
-   410
    
    [`idempotency_result_deleted`](/docs/errors/#idempotency_result_deleted): the video this session created was deleted; start a new upload.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/videos/uploads/vup_abc123/complete \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 201

```
{
  "data": {
    "id": "vid_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "original_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
    "branded_url": "https://media.example.com/vid_abc123.mp4",
    "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
    "poster_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.poster.jpg",
    "visibility": "public",
    "mime_type": "video/mp4",
    "size": 24000000,
    "width": 1920,
    "height": 1080,
    "duration_seconds": 42.417,
    "video_codec": "h264",
    "audio_codec": "aac",
    "has_audio": true,
    "fast_start": true,
    "social_compatible": true,
    "compatibility_warnings": [],
    "social_optimization": {
      "preset": "social",
      "status": "complete",
      "source": "derived",
      "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
      "size": 18400000,
      "duration_seconds": 42.417,
      "video_codec": "h264",
      "audio_codec": "aac",
      "fast_start": true,
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:01:10.000Z",
      "error": {
        "code": "optimization_failed",
        "message": "The video could not be optimized."
      }
    },
    "enrichment": {
      "status": "complete",
      "job_id": "ven_abc123",
      "requested_at": "2026-11-16T12:00:00.000Z",
      "completed_at": "2026-11-16T12:02:30.000Z",
      "transcript": {
        "status": "complete",
        "text_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.txt",
        "vtt_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.vtt",
        "segments_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.transcript.json",
        "language": "en",
        "languages": [
          "en"
        ],
        "model": "@cf/openai/whisper-large-v3-turbo",
        "segment_count": 18
      },
      "storyboard": {
        "status": "complete",
        "index_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard.json",
        "frame_count": 16,
        "sheets": [
          {
            "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.storyboard-01.jpg",
            "start_seconds": 0,
            "end_seconds": 42.417,
            "frame_count": 16
          }
        ]
      },
      "error": {
        "code": "transcription_failed",
        "message": "The video could not be transcribed."
      }
    },
    "filename": "launch-demo.mp4",
    "folder": "agents",
    "collection_id": "col_abc123",
    "metadata": {
      "run": "42"
    },
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_at": "2026-11-17T12:00:00.000Z",
    "temporary": true,
    "replayed": true,
    "signed_expires": 1795449600
  }
}
```

## Abort a multipart upload

DELETE `/v1/videos/uploads/{uploadId}`

Cancel an active multipart session: stored parts are discarded and the reserved storage and upload quota released. Only active sessions can be aborted; delete a completed video with [`delete_video`](/docs/api/videos/#delete_video).

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`uploadId`

string

Required

`upload_id` from [`create_video_upload`](/docs/api/videos/#create_video_upload).

### Responses

-   204
    
    Upload aborted and reserved quota released. No body.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`upload_not_found`](/docs/errors/#upload_not_found): no session with this id in the project.
    
-   409
    
    [`upload_complete`](/docs/errors/#upload_complete): the upload already committed; delete the video with [`delete_video`](/docs/api/videos/#delete_video).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X DELETE https://api.pixelvault.dev/v1/videos/uploads/vup_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 204

Upload aborted and reserved quota released. No body.
