Run a system

How a run works

1. POST /v1/system-runs with what you want made (prompt), and optionally the system. You get a run_id at once, and the run is running.
2. Read GET /v1/system-runs/{run_id} about every 10 seconds. message is what the run says now; messages is the whole conversation.
3. When the run needs you, waiting_for says what for:
   • answers (status needs_input): read questions[] (some have options) and answer them all in one reply: POST /v1/system-runs/{run_id}/messages with {"text": "..."}. With no questions, the run paused: say go on with POST /v1/system-runs/{run_id}/approve.
   • quote (status needs_approval): the next paid step costs about quote_usd. Say yes with POST /v1/system-runs/{run_id}/approve, or ask for a change with a reply.
   • checkpoint (status needs_approval): a script, frames or a first clip waits in checkpoints[]. Approve it (POST /v1/system-runs/{run_id}/approve, optionally with its checkpoint_id), or reply with a change.
4. When the run is succeeded, output.videos[].url holds the finished video (and output.images, output.audio; output.text holds a written answer, such as hooks or a script). Download it right away.

Send "approval": "auto" with max_price_usd and the run goes on by itself while its media spend stays within that cap; anything over it waits for your yes. You can still reply or cancel while it works.

curl -s https://vidlab.ai/v1/system-runs \
  -H "Authorization: Bearer $VIDLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: coffee-ad-1" \
  -d '{"system": "drama-ad", "prompt": "Make a Drama Ad for my coffee brand: a woman in her kitchen, warm morning light", "inputs": {"images": ["https://example.com/bag.png"], "aspect_ratio": "9:16"}}'

The systems

GET /v1/system-runs/catalog (no key) lists them: id, name, description (one line of what it is), kind (video or image) and a thumbnail_url. available is false while running systems is not switched on yet. A system is a way of making a video, not a product with a fixed length or price: what a run costs depends on what you ask, and each paid step is quoted before anything is spent. The answer may be cached for 10 minutes. The dashboard shows them on the Systems page, where each has a "Copy API call".

The request

An Idempotency-Key header makes a resend find the same run for the rest of the UTC day.

Endpoints

Every call but the catalogue needs your key. Dashboard keys have full access; a scoped key needs the runs scope.

The run

What it costs

A run is billed from your balance, the same balance as your generations:

• Each media step (an image, a clip, a voice-over) is an ordinary generation at that model's price, never above the price you approved. Each one shows in your usage logs.
• The run's own planning and writing is billed as it goes and shows in your usage logs under the system's name. price.run_usd is the total so far.
• When a run starts, a small amount (50 credits) is set aside, and it is released when the run ends.

A run stops if your balance runs out (error.code api_wallet_exhausted): what it made stays on the run. A cancel stops the billing at once. A run still going after 72 hours is stopped.

Errors