Video clips and clip batches

Make one clip

1. Open Quick clip in the web app, on the One clip tab.
2. Write the prompt, choose the duration, the ratio and the resolution, and add a reference image if the clip should start from your own picture.
3. Review the quote, then start the clip. The price is stored when the quote is made.
4. When the clip is ready, download it as an MP4 file.

Reference image

• With a reference image the clip is made image to video: it starts from your picture.
• The image must be a ready JPG, PNG or WebP image in the same workspace. Anything else is refused with VIDEO_CLIP_REFERENCE_INVALID.
• A reference_asset_id that does not exist in your workspace is answered with NOT_FOUND. Use an image from your own library.
• If the rights to the image are not confirmed, the quote carries the warning REFERENCE_RIGHTS_UNCONFIRMED. The warning does not block the clip; confirm that you may use the image.

Routes

Every clip is made on a route. When you do not choose one, the first ready Platform GPU route that fits your options is used. If none fits, the quote is refused with VIDEO_CLIP_ROUTE_UNAVAILABLE (HTTP 409); change the options and quote again.

• Platform GPU: the clip is made on our own GPUs and no data is sent to an external model provider.

The route badge is shown next to the quote, so you see where a clip will be made before you start it.

Clip batches

A batch turns a table into many clips: each row is one clip. Make a batch from the Batches tab of Quick clip.

1. Choose a file (CSV, TSV, TXT or XLSX) or paste one prompt per line.
2. Optionally write a template with {{column}} placeholders. Each row fills the placeholders from its own columns. Without a template, the prompt column of a row is its prompt.
3. Optionally add the columns route, duration_seconds, ratio, resolution or reference_asset_id. A value in a row replaces the batch setting for that row.
4. Choose Check and price. Every row is read and priced and nothing is written yet; a row with a problem is listed with the reason.
5. Start the batch. Starting holds the total for the whole batch; the clips then run in groups of up to 10.

product,ratio,duration_seconds
Ceramic mug,9:16,4
Linen shirt,9:16,6

Slow turntable shot of a {{product}} on a bright table

A column name is trimmed, lower-cased and has its spaces turned into underscores, so Product Name is the column product_name. A comma, a semicolon or a tab can separate the columns of a CSV file.

Batch and item states

• A batch is draft, running, paused, completed or cancelled. Open batches are drafts, running ones and paused ones.
• An item is pending, queued, running, ready, needs_attention, cancelled or deleted.
• On the batch screen you can pause, resume or cancel a batch, show its rows, and download the finished clips as a ZIP.
• An item that needs attention keeps its reason as an error code. The rest of the batch carries on.

Over MCP and REST

One clip: quote_media_task with kind set to video_clip makes a quote (free, an interactive token is enough). After the person agrees to the price, generate_media_task starts it (an execute token). get_media_task reads the state.

A batch uses three tools. create_media_batch takes the table as csv, xlsx_base64 or rows (a list of objects, column to value), plus template and the clip options. It starts at once unless start is false, which makes a free draft that a person can start in the web app. get_media_batch reads the status, the counts per state and the progress. list_media_batch_items lists the items in row order and can filter by state.

quote_media_task {"workspace_id": "<id>", "kind": "video_clip", "prompt": "A ceramic mug on a bright table, slow turn", "duration_seconds": 4, "ratio": "9:16", "request_key": "<uuid>"}
create_media_batch {"workspace_id": "<id>", "rows": [{"product": "Ceramic mug"}, {"product": "Linen shirt"}], "template": "Slow turntable shot of a {{product}} on a bright table", "ratio": "9:16", "start": false, "request_key": "<uuid>"}

The same clips and batches are available over HTTP: see the REST API. A person can follow a batch in the web app while an agent runs it.