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

Social-ready video

Goal: host an MP4 and hand a social publishing tool a URL it will accept: H.264 video, AAC audio, fast-start. PixelVault keeps your original unchanged and makes a separate compatible copy only when needed.

Prefer a browser? The Video to URL tool accepts MP4 files up to 25 MB with no signup. It returns a 24-hour URL; save the same upload to a free account and select Make it social-ready to keep both the original and a post-ready copy.

1. Upload with a social-ready copy

POST /v1/videos stores the video bytes as provided, generates a stored 640×360 JPEG poster frame, and reads bounded container metadata for duration, dimensions, codecs, and fast-start layout. X-PixelVault-Social-Ready: true enqueues a separate H.264/AAC fast-start copy in the same request. A secret API key (or signed-in dashboard session), verified email, Content-Type: video/mp4, and Content-Length are required.

Upload
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: video/mp4" \
  -H "X-PixelVault-Filename: launch-demo.mp4" \
  -H "X-PixelVault-Social-Ready: true" \
  --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",
  "social_ready_url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.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": "not_needed",
    "source": "original", "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4" }
} }

The CLI's upload --social uploads, waits for optimization, and prints the post-ready URL; JSON output keeps both original_url and social_ready_url. The REST upload response is immediate: poll GET /v1/videos/:id while social_optimization.status is pending or processing (see Async jobs), or subscribe to video.optimization.completed webhooks.

2. Check compatibility

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 for fast-start playback. Then no copy is needed (social_optimization.status: "not_needed") and social_ready_url is the original. Other valid MP4 files still upload unchanged; compatibility_warnings explains what to fix before sending the URL to a social publishing tool.

3. Optimize an existing upload

Call POST /v1/videos/:id/optimize to create or retry the same separate copy. The call is idempotent: it returns 202 while queued or processing, 200 when complete, and 200 without creating a copy when the original is already compatible. Failed jobs return their reserved monthly seconds.

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

→ { "data": {
     "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.mp4",
     "social_optimization": {
       "status": "complete",
       "source": "derived",
       "url": "https://img.pixelvault.dev/proj_xyz789/vid_abc123.social.mp4",
       "video_codec": "h264",
       "audio_codec": "aac",
       "fast_start": true
     }
   } }

Import by URL

Send application/json with an https url, optional filename, visibility, sign_expires_in, social_ready, expires_in, folder, collection_id, and custom metadata. The remote server must return Content-Length. PixelVault streams the response directly to storage, checks the downloaded size and MP4 signature, and allows the full plan limit without multipart.

curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://media.example/launch-demo.mp4","filename":"launch-demo.mp4","social_ready":true}'

Plan limits

PlanMax MP4 sizeSocial-ready output / monthTranscript + storyboard / month
Free25 MB2 minutes2 source minutes
Starter100 MB30 minutes30 source minutes
Pro250 MB120 minutes120 source minutes

Social-ready optimization accepts source MP4s up to 100 MB and 60 seconds on every plan. Transcript + storyboard enrichment accepts source MP4s up to 100 MB and 10 minutes; the remaining monthly allowance must cover the full source duration. Optimized copies, posters, transcripts, and storyboards use storage quota; the original remains downloadable and unchanged. Set X-PixelVault-Visibility: private to return signed video and poster URLs; the free plan includes 100 private assets total, and paid plans are unlimited.

Large files: resumable uploads

For files over 100 MB, create a multipart session with POST /v1/videos/uploads. Add Idempotency-Key plus the whole-file sha256 to replay initiation safely. Upload sequential parts to PUT /v1/videos/uploads/:uploadId/parts/:partNumber using the returned part_size; idempotent sessions require X-PixelVault-Part-SHA256, and an exact part retry returns replayed: true. Then call POST /v1/videos/uploads/:uploadId/complete. Finalization is replayable after a lost success response. Completed replay markers remain for 24 hours. Abort only active sessions with DELETE /v1/videos/uploads/:uploadId; delete a completed asset through DELETE /v1/videos/:id.

FILE=keynote.mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA256=$(shasum -a 256 "$FILE" | awk '{print $1}')
API=https://api.pixelvault.dev/v1/videos/uploads

# 1. Start a session (replayable with the same key + sha256)
SESSION=$(curl -sS -X POST "$API" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: keynote-v1" \
  -d "{\"filename\":\"$FILE\",\"size\":$SIZE,\"sha256\":\"$SHA256\"}")
UPLOAD_ID=$(echo "$SESSION" | jq -r .data.upload_id)
PART_SIZE=$(echo "$SESSION" | jq -r .data.part_size)

# 2. Upload parts in order, each with its own SHA-256
split -b "$PART_SIZE" -d -a 4 "$FILE" part-
N=1
for PART in part-*; do
  curl -sS -X PUT "$API/$UPLOAD_ID/parts/$N" \
    -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
    -H "X-PixelVault-Part-SHA256: $(shasum -a 256 "$PART" | awk '{print $1}')" \
    --data-binary @"$PART"
  N=$((N + 1))
done

# 3. Complete (safe to repeat after a lost response)
curl -sS -X POST "$API/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Direct uploads with an Idempotency-Key must also send X-PixelVault-Content-SHA256; see Idempotency for the exact replay rules.

Lifecycle and organization

expires_in accepts 60–2,592,000 seconds on direct, URL, and multipart initiation. At expiry, PixelVault fails active optimization/enrichment jobs, returns reserved job quota, and deletes the original, poster, optimized copy, transcripts, and storyboards. The hourly sweep can lag by up to about two hours. sign_expires_in only expires bearer URLs and never deletes bytes. No video TTL default changed. Use folder, an existing same-visibility collection_id, and custom metadata at upload; replace them later with PATCH /v1/videos/:id. Filter discovery with GET /v1/videos?folder=agents&collection_id=col_…&meta[run]=42. See Expiry & retention and Organize media.

Other video operations

List videos with GET /v1/videos?page=1&per_page=20, read one with GET /v1/videos/:id, generate transcript + storyboard artifacts with POST /v1/videos/:id/enrich (guide), analyze/backfill metadata with POST /v1/videos/:id/analyze, retry/backfill its poster with POST /v1/videos/:id/poster, mint expiry-matched signed URLs for the original and all derivatives with POST /v1/videos/:id/sign-url, and delete the original plus its derivatives with DELETE /v1/videos/:id. CDN responses support HEAD and single Range: bytes=… requests for seeking.

Next steps