Skip to content

Videos

Picora hosts videos with adaptive HLS streaming powered by Bunny.net (overseas) or Aliyun VOD (mainland). Upload once; viewers get the best quality their connection supports.

Video hosting requires pro or pro_plus plan. See plan comparison.

Quick upload via dashboard

  1. Open Library → Videos
  2. Drag a video file or click Upload
  3. Wait for upload — progress bar shows percentage
  4. After upload, the video enters transcoding state (typically 1-5 minutes for short clips, longer for HD/longer videos)
  5. When status changes to ready, copy the playback URL or embed code

Supported formats

FormatContainerNotes
MP4H.264 / H.265Most common; widely compatible
MOVH.264 / ProResiPhone / Mac native
MKVH.264 / H.265 / VP9Container with multiple codecs
WebMVP9 / VP8Web-native
AVIvariesLegacy; auto-converted to MP4 during transcoding

The transcoder produces multiple HLS variants automatically (typically 360p / 480p / 720p / 1080p depending on source).

Upload via API

Terminal window
curl -X POST https://api.picora.me/v1/videos \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F file=@trip.mp4 \
  -F title="Italy 2026 trip"

Response (immediately, status=processing):

{
  "success": true,
  "data": {
    "id": "abc123def45",
    "title": "Italy 2026 trip",
    "filename": "trip.mp4",
    "sizeBytes": 104857600,
    "status": "processing",
    "createdAt": "2026-04-27T08:00:00Z"
  }
}

Poll /v1/videos/{id} until status becomes ready, then playback_url and thumbnail_url are populated.

Transcoding lifecycle

[upload] → status=processing → (Bunny / VOD transcodes) → webhook → status=ready
                                                        OR → status=failed

Typical transcoding time:

Source durationTranscoding time (approx)
30 seconds1-2 minutes
5 minutes3-5 minutes
30 minutes10-20 minutes
1 hour20-40 minutes

You can keep using the dashboard while transcoding runs in the background.

Thumbnail (v0.11.1)

Each ready video has an automatically extracted thumbnail at the 5-second mark. Access it via the thumbnail_url field on the video metadata response, or from the Library list.

You can replace the thumbnail manually:

  1. Open the video detail page
  2. Click Replace thumbnail
  3. Upload a JPEG / PNG (recommended 16:9 aspect ratio, 1280×720 px)

Custom thumbnails count against your image storage quota (small impact, typically <50 KB).

Playback URL formats

Each ready video exposes:

playback_url:  https://video.picora.me/{id}/playlist.m3u8       # HLS, recommended
direct_url:    https://video.picora.me/{id}/original.mp4         # MP4 fallback (where supported)
thumbnail_url: https://media.picora.me/thumbnails/{id}.jpg

Embed in HTML using a player like Plyr / Video.js / hls.js:

<video controls poster="https://media.picora.me/thumbnails/{id}.jpg">
  <source src="https://video.picora.me/{id}/playlist.m3u8" type="application/x-mpegURL">
</video>

Bandwidth degradation {#degrade-strategy}

When your monthly video bandwidth quota is exhausted, playback auto-degrades to 360p. This is silent — viewers see lower quality but no error. See Bandwidth & degradation for details.

Past 120%, playback is fully suspended (HTTP 451) until next month or upgrade.

Visibility

Same as images: isPublic flag controls whether the playback URL works for anonymous viewers. Toggle from the dashboard or via PATCH API.

For private videos, viewers need a signed URL (see API Reference — Videos for the signing flow).

Deletion

Terminal window
curl -X DELETE https://api.picora.me/v1/videos/{id} \
  -H "Authorization: Bearer sk_live_..."

Deletion:

  • Removes the row from med_media table
  • Asks Bunny.net / Aliyun VOD to delete all transcoded variants and originals (asynchronous, may take minutes)
  • Decrements quota:video_storage and quota:media_storage
  • Purges thumbnail and CDN cache

Common issues

“403 Forbidden — video disabled” — your plan doesn’t include video. Upgrade to pro / pro_plus.

“422 Validation error — file too large” — exceeds your plan’s video_max_file_bytes (500 MB / 2 GB). Compress with HandBrake or upload from a higher tier.

“422 — video too long” — exceeds video_max_duration_seconds (30 min / 2 hours).

“Status stuck at processing for >1 hour” — transcoding may have failed silently. Check the video detail page for status changes; if still processing after 24h, contact support with the video ID.

“Playback returns 451” — your monthly video bandwidth has exceeded 120%. See Bandwidth & degradation.

“Choppy playback at 1080p” — viewer’s network can’t sustain it. HLS auto-falls back; if not, check that you’re using .m3u8 URL not .mp4.