Videos

Import or reserve a video

Creates a library video from a supported URL, direct HTTPS asset, or client upload reservation. URL imports begin immediately. For upload, use the returned object path and completion route with createVideoUpload. Optional product recipes are staged to run after ingest prerequisites. products.packaging.thumbnail accepts true/{} (faceless Creative) or the full zero-prompt object (Creative thumbnail-v2 or Precision thumbnail-precision, including opaque key-moment detect). Optional folderId places the video in an existing Studio folder in the same personal or workspace library. Create folders with POST /folders or in Studio. Unknown or inaccessible folders return 404. Required scope: videos:write.

post/videos

Request

Base URL
https://api.braiv.co/v1
Auth
- HTTP bearer
- or API key in header X-Api-Key

Headers

Idempotency-Keystring

Caller-generated key for safe POST retries. The API retains the first JSON response for 24 hours. Reusing a key with another path or body returns 409 IDEMPOTENCY_REPLAY.

Request body

workspaceIdstring

Destination workspace. Omit for the caller's personal library.

folderIdstring

Existing Studio folder id in the same library as the import. The video is added to that folder (UserVideos.tags). Create folders with POST /folders or in Studio.

Example request

{
  "products": {
    "dubs": [
      {
        "languages": [
          "en"
        ]
      }
    ],
    "shorts": {
      "clipSelectionPrompt": "Prioritise the practical walkthrough and exclude introductions."
    },
    "packaging": {
      "thumbnail": {
        "thumbnailTranslationLanguageCodes": [
          "en"
        ]
      }
    }
  }
}

Response

Video accepted. Poll the returned jobs; upload reservations also include upload instructions.

videoIdstring required

Created library video ID.

status'queued' | 'processing' | 'ready' | 'failed' required

Normalized lifecycle shared by jobs and video projections: queued is waiting to start, processing is running, ready completed successfully, and failed reached a terminal error.

Example response

{
  "video": {
    "defaultLanguageCode": "en",
    "import": {
      "language": "en"
    },
    "transcript": {
      "language": "en"
    }
  },
  "jobs": [
    {
      "language": "en"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.