Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

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

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). 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).

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 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; 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 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 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

Request
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 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 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; a retry while the first request is still running returns 409 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, and filter with list_videos. Private videos (free plan: 100 private assets) return signed video and poster URLs.

Prefer a browser? The Video to URL tool 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.

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

Request
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

Request
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

Request
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 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

Request
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 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 → 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

Request
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 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 → 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

Request
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

Request
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

Request
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

Request
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:

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. 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

Request
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.

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

Request
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.

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: 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: the assembled bytes are not an MP4. validation_error: bad X-PixelVault-Sign-Expires-In or X-PixelVault-Social-Ready.

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    video_upload_forbidden: publishable keys cannot use the video and audio endpoints. email_verification_required: verify the account email first. account_suspended: the account is suspended.

  • 404

    upload_not_found: no session with this id in the project (it may have expired).

  • 410

    idempotency_result_deleted: the video this session created was deleted; start a new upload.

  • 429

    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
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.

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.

Responses

Request
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.