Create a video batch
POST/api/v1/videos/batch
Create a batch under one batch_id — either an empty placeholder for later file uploads (kind='file'), or an inline set of URL rows submitted immediately (kind='url').
kind='file': usually you don't need this directly — POST /v1/videos/batch/upload creates a batch of its own when no batch_id is supplied. Use this only when you need to pre-create the batch and upload files across multiple later requests.
kind='url': every row in items is validated and either submitted, linked to an existing job for the same URL, or skipped. The response's own items array carries each row's outcome — source_url, video_id, job_id, status, error — in request order and 1:1 with what you sent, so mapping URLs to video ids no longer needs a follow-up call. It is never truncated; the request's 500-item cap is what bounds its size. submitted still means 'handed to the pipeline' — poll GET /v1/videos/batch/{batch_id} (or GET /v1/videos/{video_id}) for what actually happened after submission. Have a csv/xlsx file instead of an already-parsed URL list? Use POST /v1/videos/batch/upload-sheet instead.
Request
Responses
- 201
- 400
- 401
- 403
- 422
- 500
Successful Response
Request rejected — unsupported kind, or a field that doesn't apply to the given kind (e.g. non-empty items with kind='file').
Missing or invalid API key. Add Authorization: Bearer vuf_live_<keyid>.<secret>.
Key used outside the public API roots (/api/v1, /api/v1.1).
Request body failed validation.
Upstream service error — usually safe to retry.