Videos

Videos are the core resource in Moviie. Each video belongs to exactly one collection within your organization.

Video statuses

External reference IDs

Every video accepts an optional reference_id: a client-side identifier you can use to link the Moviie video to a row in your own database (a course, lesson, product SKU, etc.). It is:

• Free-form, 1–128 characters.
• Unique within an organization. Two videos in the same org cannot share a reference_id. Different organizations can.
• Filterable via GET /v1/videos?referenceId=….
• Editable via PUT /v1/videos/{id}: pass null to clear.

Setting a value already used by another video in the same org returns HTTP 409.

Available operations

Subtitles and translations

Every video can have one source subtitle in its spoken language, plus any number of translations into other languages. Both are made of timed cues (start, end, text) and can be fetched, edited, downloaded, and shown in the player.

Lifecycle

1. Source subtitle: fetch it with GET /v1/videos/{id}/subtitle. available is false until one exists. Edit its cues with PUT /v1/videos/{id}/subtitle, control whether the player shows it by default with PUT /v1/videos/{id}/subtitle/display, and regenerate or revert it. When the transcript changes, transcriptDrift turns true: regenerate to refresh.
2. Translations: start one or more with POST /v1/videos/{id}/translations, passing the target languages from supportedLanguages. Translation requires a source subtitle (sourceAvailable: true) and consumes credits proportional to the video duration, per language. Each language is produced asynchronously: poll GET /v1/videos/{id}/translations or GET /v1/videos/{id}/translations/{lang} until status is ready.
3. Editing a translation: PUT /v1/videos/{id}/translations/{lang} edits cue text only; timings stay locked to the source subtitle, so changing a cue's timing or count returns 422. Regenerate re-runs the translation; revert discards manual edits.

Listing and downloading

GET /v1/videos/{id}/subtitle-tracks returns the source subtitle and every translation in a single list: each with its status and cueCount: which is handy for building a track picker. Download any ready track as a WebVTT (.vtt) file with GET /v1/videos/{id}/subtitle-tracks/{lang}/download.

Credits and limits

• Starting or regenerating a translation returns 402 when the credit balance is insufficient.
• Translation endpoints are rate limited and return 429 with a Retry-After header when a limit is hit.
• A translation can be started only after a source subtitle exists; otherwise the request returns 409.

Already have subtitle files? You can also upload .vtt or .srt tracks directly with POST /v1/videos/{id}/captions.