POST https://api.percify.io/v3/playground/v1/batches runs one model over many prompts. The server drives the batch, so you can hang up: each prompt becomes an ordinary generation, charged and refunded on failure exactly as POST /v1/run is. Start it, then poll it, or receive a webhook when it settles.
This is the difference between the API and the in-app Batch Mode page, which runs its loop in the browser and stops when you close the tab.
Start a batch
cURL
Body
string
required
A model that takes a text prompt.
GET /v1/models lists them.string[]
required
1 to 50 prompts. Each one becomes a single generation.
object
Inputs shared by every run, such as quality or aspect ratio. The prompt is filled in per item, so leave it out.
string
A saved persona name or id, applied to every run in the set.
integer
A hard ceiling. It is checked against what has actually been charged before each submission, so the batch stops itself at the ceiling rather than passing it. Omit it and the budget is the full estimate, which the response returns up front.
integer
How many run at once, 1 to 5. Default 3.
201 means the batch started. A 400 means no prompts, more than 50, an unknown model, a model with no prompt field, a budget below the cost of one run, or not enough credits.
Poll a batch
GET https://api.percify.io/v3/playground/v1/batches/{id} returns the batch state with per-item status and output URLs.
cURL
404 means no batch with that id on this account.
Stop a batch
POST https://api.percify.io/v3/playground/v1/batches/{id}/stop stops new prompts being submitted. Generations already in flight still finish and are still charged, and nothing already produced is lost.
List recent batches
GET https://api.percify.io/v3/playground/v1/batches returns recent batches, newest first. Takes an optional limit.
From MCP instead
The same thing is available to an MCP client asbatch_generate, with get_batch, list_batches and stop_batch. See the Percify MCP server.
FAQ
What happens if my process dies mid-batch?
What happens if my process dies mid-batch?
Nothing is lost. The plan is written down before the first submission, and polling the batch resumes the prompts it had not reached.
How is a batch charged?
How is a batch charged?
Per generation, at the model’s normal price, exactly as a single run. A generation that fails is refunded.
Can I guarantee it will not spend more than a set amount?
Can I guarantee it will not spend more than a set amount?
Yes, that is what
budgetCredits is for. It is enforced before each submission rather than reported afterwards, so the batch stops at the ceiling instead of passing it.What is the largest batch?
What is the largest batch?
50 prompts in one call. Start several batches for more.
Related
Batch Mode in the app
The same idea with a UI, driven by the browser.
Start a single generation
POST /v1/run, the call each batch item becomes.
Estimate a cost first
Price a run before you start it. It never charges.
Webhooks
Receive the result instead of polling.