Ask our agent

How a run works

1. POST /v1/agent/runs with your prompt. You get a run_id at once, and the run is running.
2. Read GET /v1/agent/runs/{run_id} about every 10 seconds. message is what the agent says now; messages is the whole conversation.
3. When the agent 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/agent/runs/{run_id}/messages with {"text": "..."}. With no questions, the agent paused: say go on with POST /v1/agent/runs/{run_id}/approve.
   • quote (status needs_approval): the next paid step costs about quote_usd. Say yes with POST /v1/agent/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/agent/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 agent 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/agent/runs \
  -H "Authorization: Bearer $VIDLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: coffee-ad-1" \
  -d '{"prompt": "A 20 second 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 request

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

Endpoints

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

What it can make (Systems)

GET /v1/agent/systems (no key) lists the agent's systems: id, name, description (what it makes), kind (video or image), length_seconds (min, max), the inputs it asks for (name, label, type, required, options), a thumbnail_url and a rough price_usd (min, max). available is false while the agent is not switched on yet; the list is then our formats. To make one, start a run whose prompt names it ("Make a Drama ad for ..."). The answer may be cached for 10 minutes. The dashboard shows it as Systems.

The run

What it costs

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

• Each model 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 agent's own work (its thinking and writing) is billed as it goes and shows in your usage logs as "Agent". price.agent_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