Batch Generation & AI Suggestions

Generate multiple items in a single API call, and use AI vision to get smart action suggestions for your mascot.

Batch Generation

Send up to 10 generation requests in a single call. Each item in the requests array follows the same format as the single generate endpoint. All requests run in parallel. The endpoint returns 202 Accepted with the list of queued jobs - generation runs asynchronously.

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": "jumping up and down excitedly, confetti motion",
        "duration": 4,
        "loop": true
      }
    ]
  }'

When to Batch vs Sequential

Use batch when you know all the items upfront - for example, generating a full set of poses for a new mascot. All items are created and queued in parallel, which is faster than sending individual requests.

Use sequential requests when each generation depends on the previous result - for example, generating an image first, then animating it with source_image_asset_id. You need the first job to complete before starting the second.

AI Action Suggestions

Ask the AI to suggest action poses for your mascot. The endpoint analyzes your mascot's reference images (or the first completed image in the mascot) and returns 6-8 action names that suit the character. This is free - no credits are deducted.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/suggestions \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Suggestions automatically exclude items that already exist in the mascot, so you can call it repeatedly as you build out your pose library.

Partial acceptance

A batch is not an atomic transaction. Check every entry in data.jobs for a real job_id; the outer 202 response does not guarantee that every request was accepted. Poll accepted jobs individually, preserve successful work, and review missing entries before retrying. Do not resend the entire batch after an uncertain response.