Batch generation and AI suggestions
Queue up to 10 generations in one call, and get free pose ideas for your mascot.
Batch Generation
Each entry in requests uses the same fields as /generate, except speech, and all run in parallel. The call returns 202 Accepted with the queued jobs.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate-batch \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"requests": [
{
"type": "image",
"name": "Waving",
"image_prompt": "waving hello with a friendly smile"
},
{
"type": "image",
"name": "Thinking",
"image_prompt": "hand on chin, looking up thoughtfully"
},
{
"type": "animation",
"name": "Celebrating",
"image_prompt": "jumping with arms raised in celebration",
"animation_prompt": "0.00-0.90s: crouches, wriggling with excitement. 0.90-2.00s: jumps up with both arms high as confetti bursts around it. 2.00-3.10s: lands and bounces, confetti drifting down. 3.10-4.20s: jumps again, arms still high. 4.20-5.17s: lands and crouches into the next jump.",
"animation_model": "standard",
"duration": 5,
"loop": true
}
]
}'When to Batch vs Sequential
Batch when you know every item up front, such as a full pose set for a new mascot. Send requests one by one when a generation needs an earlier result, such as animating a new image with source_image_asset_id after its job completes.
AI Pose Ideas
Get pose ideas written for your mascot from its references and personality, the same ideas Studio offers, for free. Each idea has a name, a pose for the still picture and an animation with the matching motion. suggestions lists the names, as before.
curl "https://api.masko.ai/v1/mascots/MASCOT_ID/suggestions?count=3" \
-H "Authorization: Bearer masko_YOUR_API_KEY"Send an idea's name as name and its pose as image_prompt in a batch, and its animation as animation_prompt with type: "animation".
countsets how many ideas, 1 to 15 (default 8).- The ideas are saved on the mascot and returned again without being written anew, so reading them twice gives the same list. Pass
refresh=truefor new ones. Ideas saved by an older idea writer are written again once, for free, on the next read. - A read-only key never replaces current saved ideas: with it,
refresh=truereturns new ideas without saving them. variant_idwrites ideas for an approved variant. These are always new and not saved.- Ideas whose name the mascot already has as an item are left out, so you can call it again as the pose library grows.
- Writing new ideas counts toward a daily limit of 300 free ideas per account, shared with background ideas, voice ideas, voice rewrites and talking dry runs. Past it, the call returns
429with coderate_limited. Returning saved ideas does not count.
Partial acceptance
A batch is not atomic: the outer 202 does not mean every request was accepted. Check each entry in data.jobs for a real job_id, poll accepted jobs individually, and review missing entries before retrying. Never resend the whole batch after an uncertain response.
