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
| Property | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string | Video id ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
kind | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url | string (uri) | Seekable CDN URL of the original (supports | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
original_url | string (uri) | The stored original MP4. Equal to | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
visibility | string | Private videos are served only through signed URLs. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
compatibility_warnings | array of object | What to fix before sending the URL to a social publishing tool. Empty when | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Child properties of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Property | Type | Description |
|---|---|---|
code | string | |
message | string |
social_optimizationState 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
| Property | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
preset | string | ||||||||||
status | string | Poll | |||||||||
source | string |
| |||||||||
url | string (uri) | The social-ready MP4 (signed for private videos). Present when status is | |||||||||
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 | |||||||||
Child properties of | |||||||||||
| Property | Type | Description |
|---|---|---|
code | string | |
message | string |
enrichmentState of the optional transcript + storyboard job. Generated artifacts inherit the video's visibility and signed-URL expiry.
Child properties of enrichment
| Property | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
status | string | Poll | |||||||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||||||||
Child properties of | |||||||||||||||||||||||||||||||||||
| Property | Type | Description |
|---|---|---|
status | string | |
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. |
storyboardStoryboard index plus bounded JPEG contact sheets of sampled frames.
Child 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 | |||||||||||||||||
| Property | Type | Description |
|---|---|---|
url | string (uri) | |
start_seconds | number | |
end_seconds | number | |
frame_count | integer |
errorPresent when status is failed. Call enrich_video again to retry with a new job_id.
Child properties of error
| Property | Type | Description |
|---|---|---|
code | string | |
message | string |
filenamefolderLogical folder used for organization and list filtering.
collection_idCollection membership; the collection's visibility matches the video's.
metadataCaller-managed custom metadata (max 50 top-level keys, 4 KB).
created_atexpires_atDeletion 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.
temporaryPresent and true only when expires_at is set.
replayedPresent and true when an idempotent retry returns an existing video.
signed_expiresUnix timestamp when private original and derivative bearer URLs expire. Private videos only.
{
"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
| Name | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | Page number, from 1. |
per_page | integer | Optional | Videos per page (max 100). |
collection_id | string | Optional | Only videos in this collection. |
folder | string | Optional | Exact logical-folder match. |
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. |
Responses
- 200
Paginated videos
- 400
invalid_folder: bad folder name.validation_error: malformed or conflicting metadata filter. - 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
no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl "https://api.pixelvault.dev/v1/videos?per_page=20" \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| 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 |
X-PixelVault-Visibility | string | Optional | Direct uploads: |
X-PixelVault-Sign-Expires-In | integer | Optional | Direct uploads: lifetime in seconds of the returned private video and poster URLs. Never deletes the video. |
X-PixelVault-Social-Ready | boolean | Optional | Direct uploads: |
Idempotency-Key | string | Optional | Up to 255 non-space printable ASCII characters; replays for 24 hours within this project. Conflicting inputs return 422 |
X-PixelVault-Content-SHA256 | string | Optional | Hex SHA-256 of the MP4 bytes, verified while streaming. Required with |
X-PixelVault-Folder | string | Optional | Direct uploads: logical folder (letters, numbers, hyphens, underscores; max 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. |
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | Required | Public https URL of the MP4. Must return |
filename | string | Optional | Original filename; defaults to the URL's last path segment. |
visibility | string | Optional | |
sign_expires_in | integer | Optional | Lifetime in seconds of the returned private URLs. |
social_ready | boolean | Optional | Enqueue a separate social-ready copy while preserving the original. Sources must be at most 100 MB and 60 seconds. |
folder | string | Optional | Logical folder. |
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 |
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: not an MP4 container, or under 16 bytes.missing_file: empty body.checksum_mismatch: the bytes do not matchX-PixelVault-Content-SHA256.idempotency_checksum_required: a direct upload withIdempotency-Keyneeds the checksum header.invalid_json/missing_url: bad URL-import body.url_length_required: the remote server sent no validContent-Length.invalid_url,unsupported_scheme,blocked_host,url_fetch_failed: the URL could not be imported.invalid_upload: the stored upload was incomplete.invalid_folder,validation_error: a bad header or field (filename, visibility,sign_expires_in, social-ready flag, metadata,expires_in,collection_idorIdempotency-Key). - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
upload_limit_reached,storage_limit_reached,private_limit_reached: a plan quota is full. - 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
collection_not_found: no such collection in the project.no_project: the signed-in account has no project. - 409
idempotency_in_progress: an upload with thisIdempotency-Keyis still running; the error also carriesupload_id,asset_idandexpires_at. Retry later. - 410
idempotency_result_deleted: the video created with thisIdempotency-Keywas deleted; use a new key. - 411
length_required: a direct upload needs a validContent-Length. - 413
multipart_required: direct uploads over 100 MB must usecreate_video_upload.file_too_large: larger than the plan's video limit (25 MB Free, 100 MB Starter, 250 MB Pro).url_too_large: the remote file exceeds the plan limit.optimization_source_too_large:social_readywith a source over 100 MB. - 415
unsupported_media_type:Content-Typemust bevideo/mp4orapplication/json. - 422
idempotency_key_reuse: theIdempotency-Keywas already used with different URL, bytes, visibility, TTL, metadata, folder or collection inputs.collection_visibility_mismatch: the collection's visibility differs from the video's. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
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 {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Responses
- 200
Video metadata
- 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
video_not_found: no video with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/videos/vid_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
metadata | object nullable | Optional | Replaces the stored metadata (not merged). |
folder | string nullable | Optional | New logical folder. |
collection_id | string nullable | Optional | An existing collection with the same visibility. |
Responses
- 200
Updated video
- 400
validation_error: the body is not JSON, has none ofmetadata,folder,collection_id, or a value is invalid.invalid_folder: bad folder name. - 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
video_not_found: no video with this id in the project.collection_not_found: no such collection.no_project: the signed-in account has no project. - 413
payload_too_large: the request body is larger than 16 KB. - 422
collection_visibility_mismatch: the collection's visibility differs from the video's. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
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"}' {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Responses
- 200
Deleted
- 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
video_not_found: no video with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X DELETE https://api.pixelvault.dev/v1/videos/vid_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| 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: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
optimization_limit_reached: the monthly social-ready allowance cannot cover this duration. - 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
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: the source exceeds 100 MB. - 422
video_metadata_unavailable: the MP4 metadata could not be read.video_duration_unavailable: the duration is unknown.optimization_duration_too_long: longer than 60 seconds. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After. - 503
optimization_unavailable: optimization is temporarily unavailable; nothing was charged.
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/optimize \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Responses
- 200
Enrichment already complete
- 202
Enrichment queued or processing
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
enrichment_limit_reached: the shared monthly media-enrichment allowance cannot cover this duration. - 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
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: the source exceeds 100 MB. - 422
video_metadata_unavailable: the MP4 metadata could not be read.video_duration_unavailable: the duration is unknown, invalid or under 1 second.enrichment_duration_too_long: longer than 10 minutes. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After. - 503
enrichment_unavailable: frame extraction or transcription is temporarily unavailable; nothing was charged.
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/enrich \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Responses
- 200
Analyzed video
- 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
video_not_found: no video with this id in the project.no_project: the signed-in account has no project. - 422
video_metadata_unavailable: the MP4 metadata could not be read. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/analyze \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Responses
- 200
Video with
poster_url - 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
video_not_found: no video with this id in the project.no_project: the signed-in account has no project. - 422
poster_generation_failed: no frame could be extracted.poster_too_large: the extracted frame exceeds 2 MB. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After. - 503
poster_unavailable: frame extraction is temporarily unavailable; retry later.
curl -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/poster \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Video id. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
expires_in | integer | Optional | Lifetime of every URL, in seconds. |
Responses
- 200
Expiry-matched signed URLs for every available artifact
- 400
invalid_expires_in:expires_inis not an integer between 60 and 2592000. - 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
video_not_found: no video with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
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}' {
"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_uploadwith the whole-filesize(andsha256when usingIdempotency-Key)upload_video_partfor parts 1, 2, … in order, eachpart_sizebytes except the lastcomplete_video_uploadto validate and commit the video (signed-URL lifetime and social-ready flag are set there)- or
abort_video_uploadto 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. 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
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | Up to 255 non-space printable ASCII characters; replays for 24 hours within this project. Requires |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
filename | string | Required | Original filename, 1–255 UTF-8 bytes. |
size | integer | Required | Whole-file size in bytes. |
visibility | string | Optional | |
sha256 | string | Optional | Whole-file hex digest used to detect conflicting retries. Required with |
folder | string | Optional | Logical folder. |
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. |
Responses
- 200
Idempotent replay of an active or completed session
- 201
Multipart session created
- 400
validation_error: missing or invalidfilename,size(at least 16 bytes),visibility,sha256,metadata,expires_in,collection_idorIdempotency-Key.invalid_folder: bad folder name.idempotency_checksum_required:Idempotency-Keyneedssha256. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
upload_limit_reached,storage_limit_reached,private_limit_reached: a plan quota is full. - 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
collection_not_found: no such collection in the project.no_project: the signed-in account has no project. - 410
idempotency_result_deleted: the video created with thisIdempotency-Keywas deleted; use a new key. - 413
file_too_large:sizeexceeds the plan's video limit. - 422
idempotency_key_reuse: theIdempotency-Keywas already used with different inputs.collection_visibility_mismatch: the collection's visibility differs from the video's. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
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
}' {
"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
| Name | Type | Required | Description |
|---|---|---|---|
uploadId | string | Required |
|
partNumber | integer | Required | 1-based part number; the next part expected is one more than the parts stored. |
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 |
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: bad part number, the part is out of order, orContent-Lengthis missing or over 100 MB.part_checksum_required: the session has anIdempotency-Key, soX-PixelVault-Part-SHA256is required.checksum_mismatch: the bytes do not match the header. - 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 active or completed session with this id in the project (it may have expired). - 409
upload_complete: the session is already complete.part_already_uploaded: that part exists with different or unverifiable bytes.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: the parts would exceed the declaredsize. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
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 {
"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
| Name | Type | Required | Description |
|---|---|---|---|
uploadId | string | Required |
|
Headers
| Name | Type | Required | Description |
|---|---|---|---|
X-PixelVault-Sign-Expires-In | integer | Optional | Lifetime in seconds of the returned private video and poster URLs. |
X-PixelVault-Social-Ready | boolean | Optional |
|
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: badX-PixelVault-Sign-Expires-InorX-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. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/videos/uploads/vup_abc123/complete \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
uploadId | string | Required |
|
Responses
- 204
Upload aborted and reserved quota released. No body.
- 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. - 409
upload_complete: the upload already committed; delete the video withdelete_video. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X DELETE https://api.pixelvault.dev/v1/videos/uploads/vup_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY"