<!-- Markdown twin of https://pixelvault.dev/docs/guides/social-ready-video/ -->

# 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](/tools/video-to-url/) 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`](/docs/api/videos/#upload_video) 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

curlNode.jsPythonCLI

```
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`](/docs/api/videos/#get_video) while `social_optimization.status` is `pending` or `processing` (see [Async jobs](/docs/async-jobs/)), or subscribe to `video.optimization.completed` [webhooks](/docs/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`](/docs/api/videos/#optimize_video) 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

Plan

Max MP4 size

Social-ready output / month

Transcript + storyboard / month

Free

25 MB

2 minutes

2 source minutes

Starter

100 MB

30 minutes

30 source minutes

Pro

250 MB

120 minutes

120 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`](/docs/api/videos/#create_video_upload). Add `Idempotency-Key` plus the whole-file `sha256` to replay initiation safely. Upload sequential parts to [`PUT /v1/videos/uploads/:uploadId/parts/:partNumber`](/docs/api/videos/#upload_video_part) 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`](/docs/api/videos/#complete_video_upload). 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`](/docs/api/videos/#abort_video_upload); 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](/docs/idempotency/#video-and-audio) 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`](/docs/api/videos/#update_video). Filter discovery with `GET /v1/videos?folder=agents&collection_id=col_…&meta[run]=42`. See [Expiry & retention](/docs/lifecycle/) and [Organize media](/docs/guides/organize-media/).

## Other video operations

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

## Next steps

-   [Video transcripts & storyboards](/docs/guides/video-transcripts/).
-   [Share private video](/docs/guides/signed-urls/) with signed URLs.
-   [Videos API reference](/docs/api/videos/#upload_video).
