Create a draft batch
create_batchSaves a new draft batch in the template's workspace with one pending job per row, an image, or a video when outputFormat is mp4, gif, webm or mov; nothing renders and no credits are spent until run_batch. The result's creditCost is the exact number of credits run_batch will spend on these jobs. Every call creates a separate batch, so repeating a call duplicates it; changing an existing draft is update_batch's job. Rows are checked as in validate_batch, and one invalid row rejects the whole request with nothing saved. An animated template renders each image at one moment of its motion: stillTime, else the page's own still time, else the last frame; a video renders all of it and takes no stillTime. Needs templates:read and batches:create.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Batch name shown in Kalpana and used in output filenames, 1 to 200 characters | |
| rows | Yes | 1 to 500 rows. Each keys a layer by its name (case aside) or id, the key get_template_inputs gives, to a plain value: text as a string, an image as an asset id or file name, or { asset, fit, zoom, panX, panY } and { text, visible } when framing or visibility changes. rowExample in get_template_inputs is a ready row. With columns, a row is instead an array of cells in column order, which keeps large batches small. null leaves a layer at the template's own value. Layers left out keep the template's value, or the one in defaults. | |
| pageId | No | One page of the template (the designer connection's page_id). A template's pages are separate designs, each with its own inputs; the first page when omitted. | |
| columns | No | For array rows: the layer key of each cell, in order, like a spreadsheet header | |
| defaults | No | Values every row gets unless it gives its own, such as a logo or call to action shared by all rows | |
| stillTime | No | Animated templates only: the second of the motion that each image shows. Omit it to use the page's own still time (get_template_inputs stillTime), else the last frame. If the page has no still time, ask the user, because an outro or a loop can make the last frame a bad image. | |
| templateId | Yes | Template ID returned by search_templates | |
| outputFormat | No | Output format. png, jpeg and webp render one image per row and pdf one vector page; mp4 and gif render each row's whole motion as a video, and webm (VP9) and mov (ProRes 4444) as a transparent video for overlaying on other footage. Video needs an animated template (get_template_inputs isAnimated) and costs more credits per row | png |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | batchId for run_batch and the other batch tools | |
| rowCount | Yes | Jobs created, one per row | |
| creditCost | Yes | Actual credit cost to run every job in this batch. | |
| workspaceId | Yes |