Create a video

POST https://api.vidnext.ai/v1/videos
Authorization: Bearer vn_live_…
Content-Type: application/json
Idempotency-Key: 5f0c1d2e-…

{
  "prompt": "Top 10 hidden beaches in Croatia",
  "script": "(optional: your own narration)",
  "preset": "Documentary EN",
  "language": "uk",
  "duration_minutes": 8,
  "voice": { "id": "elevenlabs:21m00Tcm4TlvDq8ikWAM" },
  "thumbnails": { "enabled": true, "styles": ["auto"] },
  "channel_id": "…",
  "member": "olena@company.com",
  "label": "batch-21",
  "metadata": { "row": 42 },
  "callback_url": "https://example.com/hooks/vidnext"
}

Only prompt or script is required. The settings fields are on Choose settings; the full list is in the OpenAPI spec. Unknown fields are refused, so a typo never silently does nothing.

The answer is 202 with the video object — "status": "queued", and its id.

Prompt and your own narration

• prompt (10–40,000 characters) — what the video is about. VidNext writes the script.
• script (50–100,000 characters) — your narration, read word for word. Its length sets the video's length, so duration_minutes is ignored. With both, the prompt guides the visuals and the script is what's said.

Before a script is accepted, VidNext checks that it reads like narration and not like instructions ("write a video about…"), which the voice would otherwise read aloud. A script that looks like instructions is refused with 422 script_not_narration — move the instructions to prompt, or send "script_check": "off" to narrate it as it is.

Safe retries

Send an Idempotency-Key header (any unique string up to 200 characters, e.g. a UUID). Repeating the request with the same key returns the first video (200, header Idempotent-Replayed: true) instead of making a second one — so a timeout or a network error never doubles a video. The same key with a different body is refused with 409 idempotency_key_reused. MCP's create_video does the same with its request_id.

Only the key decides: without one, or with a new one, every request is a new video — even with the same prompt and settings. Each is made from scratch (its own script, footage and thumbnails; your script is read as written) and charged like any other video. Keys don't expire, so use a new one for every new video (a UUID), and repeat it only to retry — not a row number or a hash of the prompt you might send again.

Your own fields

• label (up to 100 characters) — filter by it later: GET /v1/videos?label=batch-21.
• metadata — up to 20 keys of your own data (text, numbers, true/false), returned with the video and in webhooks.
• callback_url — an https:// address that gets this video's events (signed like webhooks). It suits an n8n Wait node's resume URL.

The line

A video is accepted right away and starts as soon as one of your account's videos-at-once slots is free — so you can send 100 at once and they run one after another. While it waits, queue_position says where it is. If it can't start for a reason that can change (credits, plan, storage), it waits with a blocked reason and a video.blocked webhook, and starts by itself once that's fixed; after 24 hours blocked it fails.

Before accepting a video, the API runs the same checks a real start does — the preset, theme, voice, styles, music, language, channel and price — so a mistake fails at once with a clear error, not an hour later. A video is accepted only if your balance covers it.

A queued video can still be canceled: POST /v1/videos/{id}/cancel (nothing is charged). Once it has started it can't be.