Kalpana Batch

Stops a whole batch: every job still pending or processing becomes cancelled. Cancelled jobs are not charged and are final; a render already under way may finish, but its result is discarded. Jobs that already rendered keep their output and their charge. A finished batch, or a second call, changes nothing. An unknown batchId, or one from another workspace, returns Batch not found. To stop one job and let the rest render, use cancel_job; to render cancelled rows later, create_batch a new batch with them. Needs batches:create on the connection and renders:create in the user's workspace role.

Stops one job that is pending or processing: it becomes cancelled, is not charged, and cannot be resumed; a render already under way may finish, but its result is discarded. A job that already finished is left as it is. Other jobs in its batch keep rendering; to stop them all use cancel_batch. A jobId that is not in this workspace returns Job not found. Needs batches:create on the connection and renders:create in the user's workspace role.

Saves a new draft batch in the workspace with one pending job per row for each page (pages, or every page of templates), or one video per row for a flow: an image, or a video when a row's output format 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. To change an existing batch use update_batch. Rows are checked as in validate_batch, and one invalid row rejects the whole request with nothing saved. An animated page renders each image at one moment of its motion: the row's 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.

Saves up to 10 jobs, each filling one page (page) or one flow (flow, a video) with its own modifications and output: a few files without building a batch. batch adds them to an existing batch; without it they stand alone, named by output fileName or else the template's name. run false saves them pending and spends nothing. run true renders them at once, spending their creditCost when they succeed (failed renders are not charged; the whole request is refused when the credits do not cover it), and the answer waits up to 30 seconds for the files; status processing then means some still render, and get_job a few seconds later gets each file. Every issue across the jobs comes back in one error, with nothing saved. Every call makes new jobs, so after an error check get_job or get_batch_jobs before calling again. For more rows use create_batch. With run, state the cost and get the user's confirmation first. Needs templates:read and batches:create, and renders:create in the user's workspace role to run.

Returns one batch's status with its total, completed, failed and processing job counts. Rendering after run_batch happens in the background, so call it again until processing reaches 0. An unknown batchId, or one from another workspace, returns Batch not found. For many batches at once use list_batches; for per-job values and render errors get_batch_jobs; for download URLs get_batch_outputs. Needs batches:read.

Lists a batch's jobs in row order, each row's pages together, one page at a time (page from 1, up to 20 jobs a page; a page past the end is empty), with each job's ID, page or flow, modifications (the values it renders, by layer), status, render error and file. These job IDs and values are the input for update_batch and update_job; only pending jobs change, and error explains why a render failed. get_batch is lighter for overall progress. Needs batches:read.

Returns the download URLs of a batch's rendered images, one page of jobs at a time (page from 1, up to 20 jobs a page; a page past the end is empty), with each job's status and format; downloadUrl is null until that job has rendered. URLs are temporary, so a later call returns fresh ones. Row values and render errors are not included (get_batch_jobs has them), and get_batch is lighter for checking progress. inspect_image can view a downloadUrl. Needs batches:read, renders:read, and creatives:read.

Returns one job's status, modifications and, once it has rendered, its file: url, file name, size and dimensions. It answers at once; use it after create_job or run_job answered with a job still rendering, a few seconds apart. A pending job has nothing running and comes back at once; run_job starts it. For a batch's files use get_batch_outputs. An unknown jobId, or one from another workspace, returns Job not found. Needs batches:read.

Returns the inputs of one template page that batch rows can fill; pageId picks a page other than the first, since each page has its own inputs. For each input: its id, label, text or image type, whether it is required, its default (a text input's value, an image input's asset and preview), image slot size and fit, the key rows use for it (its name, or its id when two layers share the name), a text input's styles (s1, s2, ...) when it has several, and a valueExample. rowExample is a whole ready row. These keys and values are what validate_batch, create_batch, update_batch and update_job accept. Inputs the author turned off or put on hidden layers are left out unless includeDisabled or includeHidden asks for them; omittedInputs names them. Their template text still renders, so check them (dates, terms, links) when the copy changes theme; a row can still fill them by key. An animated template also gives its duration and its stillTime. The layout is not returned: to see the template use inspect_image on its previewUrl, and to find templates search_templates. Needs templates:read.

Returns the Kalpana workspace this connection covers, chosen when the user connected: its ID, name and slug, the user's role and what it allows here (permission codes, and in plain words whether it can render batches), and allowedImageDomains, the hosts upload_images will fetch an image URL from. Every other tool works in this workspace and takes no workspace ID. Call it to explain a 403 from another tool (run_batch needs renders:create, for example), or before passing image URLs to upload_images: a URL on another host is refused until an admin adds the domain in Workspace Settings > Domain Whitelisting. Working in another workspace needs a reconnect that chooses it. Needs workspaces:read.

Fetches one PNG, JPEG, or WebP image from a Kalpana URL (a template or asset previewUrl, or a downloadUrl from get_batch_outputs) and returns it as image content with its content type and byte size. Other hosts, other file types, and files over 5 MB are rejected, and a fetch gives up after 15 seconds. It shows one image per call; it does not build contact sheets or render templates, whose look comes from their previewUrl.

Lists the workspace's batches, newest first, one page at a time, with each batch's ID, name, status, and total, completed, failed, and processing job counts; total counts every match, so it also answers how many batches exist. search matches part of a batch name, ignoring case, and templateId keeps one template's batches. For one known batch ID, get_batch returns the same counts, and job details are in get_batch_jobs. Needs batches:read.

Renders a batch: every pending job is queued, and the call returns once they are queued. Images render in the background; track them with get_batch and collect them with get_batch_outputs. It spends the workspace organization's credits for the pending jobs: create_batch's creditCost, unless jobs were added or removed since. When the balance is too low nothing is queued, the error says not enough credits, and the batch stays a draft. A successful run publishes the draft; update_batch can still add, change or remove its pending jobs. An archived batch returns an error, and a batch with a pending job on a deleted template returns Template not found and queues nothing. Jobs reset to pending by update_batch or update_job render on the next call. If the workspace has webhook endpoints, they receive the results unless webhooks is false. Run it only after the user agrees to the cost; check rows first with validate_batch. Needs batches:create on the connection and renders:create in the user's workspace role.

Renders one pending or failed job on its own (from create_job, or get_batch_jobs), spending its creditCost when it succeeds; failed renders are not charged, so a failed job can be run again. It renders at once and the answer waits up to 30 seconds for the file; a job still rendering then comes back with status processing, and get_job a few seconds later gets its file. A job already rendering, rendered or cancelled is refused, so repeating the call does not render or charge twice; get_job reports it. To render a whole batch use run_batch. Run it only after the user agrees to the cost. Needs batches:create on the connection and renders:create in the user's workspace role.

Finds images to put into template image inputs: the ready PNG, JPEG and WebP files under 5 MB in the workspace, one page at a time, each with a previewUrl. With no filters it lists the most recently updated images and also names every image collection (named groups of images) with its ID and image count. collection keeps one collection's images, given by its name (ignoring case) or ID: when the user says where their images are ("the Diwali photos"), pass that name. query matches file names, and both combine. A collection name that matches none is refused with the workspace's collection names. Each image comes with its pixel width and height when known. An asset's id is what an image input takes in batch rows. inspect_image shows a previewUrl, and upload_images adds the user's own files. Needs assets:read.

Finds the workspace's templates to fill with data, one page at a time. Each comes with its ID, pixel size, input count, previewUrl and a link that opens it in Kalpana. Without query it lists the most recently updated templates. query matches an exact template ID, or words in a name, description or campaign topic; the size and preview filters narrow further. Animated templates are included and marked isAnimated: their images show one moment of the motion. The fillable inputs are not included: get_template_inputs returns them for one ID, and inspect_image shows a previewUrl. Needs templates:read.

Renames a batch and changes, adds, or removes its pending jobs in one request. update merges each listed job's modifications over its own (a key given again replaces it, null clears it back to the page's value) and replaces the output fields given; unlisted jobs are untouched. remove deletes those pending jobs permanently, and add creates new jobs from rows on pages, templates or a flow, as create_batch does, so repeating a request with add duplicates them. Processing, rendered and failed jobs cannot change, and an archived batch does not change. Nothing renders until run_batch, and adding or removing jobs changes what it costs. Needs templates:read and batches:create.

Changes one pending job that has no file yet, in a batch or on its own. modifications merge over the job's own (a key given again replaces it, null clears it back to the page's value) and output fields replace the job's, so repeating the same request gives the same result. Switching the output format to mp4, gif, webm or mov makes it a video job, which costs credits by its length and size when it renders. Failed, processing and rendered jobs are refused. Nothing renders until run_job or run_batch. For several jobs at once, or to add and remove jobs, use update_batch. Needs templates:read and batches:create.

Brings the user's own images (PNG, JPEG, or WebP, up to 5 MB each) into the workspace, optionally into a collection, which is made when no collection has that name. Without files it returns a link to the workspace's Images page (the collection's page with collection) for the user to drop the images into; after they say they are done, search_assets finds them. Images already online, such as product photos from a store, go in urls: Kalpana fetches each one (up to 20 a call, 5 MB each) and returns it recorded, with no upload step; a URL's host has to be on the workspace's domain whitelist (cdn.shopify.com is on it by default, and an admin adds others in Workspace Settings), and a URL that fails is listed in failed while the rest are stored, with a link to the settings page when its host is not whitelisted. An agent that has the files (a shell, files on disk) works in three steps: call with files (each one's SHA-256 hash, content type and size) to get one uploadUrl per file; PUT each file's bytes to its uploadUrl with that Content-Type header; then call again with done (each hash and file name) to record them. The recorded images come back with their id, the asset_id of an image input in batch rows. Image data is not accepted inline as base64. To look at an image already uploaded use inspect_image, and to find one search_assets. Needs assets:create.

Checks batch rows on what the batch renders (pages, every page of templates, or a flow's video) and reports every problem by row index and field, without saving anything or spending credits. It runs the same checks as create_batch, so rows that pass here are accepted there, while create_batch saves nothing if any row fails. Each row comes back as the server read it on each page (layer keys, text, and each image resolved to its asset id and file name), so a misread value shows before any credits are spent, with the jobs the batch would make and their creditCost. A layer name two layers share is refused with their ids: fill each by id and tell the user, who can rename one. It does not measure text, so copy longer than the template's sample can still overflow its box. Needs templates:read.