---
title: "Batch-generate multiple items"
method: POST
path: "/v1/mascots/{id}/generate-batch"
tags: ["Generate"]
---

# Batch-generate multiple items

`POST /v1/mascots/{id}/generate-batch`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/mascots/{id}/generate-batch`
- Auth: HTTP bearer

Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of `data.jobs[]`, each with its own `job_id`. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- StudioGenerateBatchBody
  - `requests` union[], required: Up to 10 generate requests run in parallel. Each request follows the same discriminated schema as /generate. Credits are deducted per request. Talking animations (speech) are sent one by one to /generate.
    - union
      - StudioGenerateImageBody: Generate a static image (pose). Cost: 1 credit.
        - `variant_id` string, uuid: Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.
        - `name` string: Name for the new item. Required when creating a new item. Omit when passing item_id.
        - `item_id` string, uuid: Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.
        - `visual_references` VisualReferenceBody[]: One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become mascot mascot references and do not update the mascot style card.
          - `asset_id` string, uuid: Existing image asset ID to use as a one-time visual reference.
          - `url` string, uri: Public image URL to use as a one-time visual reference.
          - `role` 'pose' | 'expression' | 'motion' | 'prop' | 'style' | 'scene': What the model should borrow from this image.
          - `note` string: Optional instruction for this reference, e.g. "closed-mouth smile".
        - `type` 'image', required
        - `image_prompt` string: What the character is doing in the image, e.g. "waving hello with a big smile".
      - StudioGenerateAnimationBody
        - `variant_id` string, uuid: Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.
        - `name` string: Name for the new item. Required when creating a new item. Omit when passing item_id.
        - `item_id` string, uuid: Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.
        - `animation_model` 'standard' | 'premium': Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).
        - `duration` integer: Whole seconds. Standard: 2–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated.
        - `type` 'animation', required
        - `animation_prompt` string: How the character moves, e.g. "bouncing up and down energetically". You can generate an animation directly from just this: when neither item_id nor source_image_asset_id is passed, the system generates a source image first (adds 1 credit), then animates it.
        - `image_prompt` string: Used only when no source image exists. The character description that gets passed to image generation before animation starts.
        - `source_image_asset_id` string, uuid: Completed image asset to animate, including an unattached image from POST /v1/upload. Unattached uploads owned by the caller are imported into this mascot without changing references or generating a new image; only animation credits are charged. The original upload is preserved. Non-square inputs are center-cropped to square before animation. Square inputs are reused unchanged. Use source_image_crop for explicit framing. Optional variant_id freezes the selected context for this import. Existing mascot assets retain their saved context. Prefer item_id to reuse an existing item image.
        - `source_image_crop` object: Optional square crop for the starting image: integer x, y, width, height in pixels after EXIF orientation. Defaults to a centered square for non-square images. Requires source_image_asset_id or an item_id with an existing image. Cropping is free and preserves the original file.
          - `x` integer, required
          - `y` integer, required
          - `width` integer, required
          - `height` integer, required
        - `end_image_crop` object: Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id.
          - `x` integer, required
          - `y` integer, required
          - `width` integer, required
          - `height` integer, required
        - `end_image_asset_id` string, uuid: Target pose image for a transition, including a pose from another variant. The prompt writer uses the starting and ending images plus their separate saved contexts to write the transition direction. The job records both endpoints and the exact prompt under generation_context.transition. Forces loop to false.
        - `loop` boolean: Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided.
        - `reverse` boolean: Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits.
        - `reverse_of_video_asset_id` string, uuid: Asset ID of the forward video to reverse. Required when reverse is true.
        - `auto_reverse` boolean: Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field.
        - `reverse_name` string: Name for the auto-generated reverse item. Defaults to "<item name> (Reverse)".
        - `sizes` integer[]: Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the mascot settings. No extra credit cost.
        - `speech` SpeechInput: Makes a talking animation: the mascot says this line in its voice (from its context, or its variant's), starting from item_id or source_image_asset_id and ending on end_image_asset_id (or the start image). The length comes from the speech: 5 seconds to 5 minutes at 2 credits per second. A talk longer than one take (15 seconds) is cut in its pauses into takes that start and end on the start image, then joined. The receipt adds audio and transcript assets and an estimate.
          - `script` string: What the mascot says, with movements in square brackets placed where each one starts, e.g. "[waves hello, excited] Hi! I'm Gubby. [points to the right] The docs are right here!". A feeling after a comma also steers the voice.
          - `text` string: The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used.
          - `direction` string: With text: how the mascot should perform the line, e.g. "excited about what he does, points at the docs at the end".
          - `language` string: ISO 639-1 code of the line. Omit it to detect the language from the words.
        - `dry_run` boolean: With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating.
      - StudioGenerateEditBody: Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit.
        - `variant_id` string, uuid: Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.
        - `name` string: Name for the new item. Required when creating a new item. Omit when passing item_id.
        - `item_id` string, uuid: Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.
        - `visual_references` VisualReferenceBody[]: One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become mascot mascot references and do not update the mascot style card.
          - `asset_id` string, uuid: Existing image asset ID to use as a one-time visual reference.
          - `url` string, uri: Public image URL to use as a one-time visual reference.
          - `role` 'pose' | 'expression' | 'motion' | 'prop' | 'style' | 'scene': What the model should borrow from this image.
          - `note` string: Optional instruction for this reference, e.g. "closed-mouth smile".
        - `type` 'edit', required
        - `edit_instructions` string, required: What to change on the source asset, e.g. "add a santa hat". Required.
        - `source_image_asset_id` string, uuid: Asset ID of the image to edit. Use `data.asset_ids.image` from a previous /generate response. If you pass `item_id`, the source is resolved from the item automatically.
        - `source_video_asset_id` string, uuid: Completed 4–30 second video in this mascot to edit at 720p. Duration and aspect ratio are preserved. Uses the source clip and its source item. For transition clips, edits preserve both saved endpoint identities and their order; variant_id does not restyle the whole clip. The edit prompt is recorded in generation_context.transition_edit.
      - StudioGenerateLogoBody: Generate a logo master plus a validated transparent version and resized exports. Native alpha is reused when valid; otherwise the transparent version removes the background. The master retains intentional backgrounds. Cost: 5 credits.
        - `variant_id` string, uuid: Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.
        - `name` string: Name for the new item. Required when creating a new item. Omit when passing item_id.
        - `item_id` string, uuid: Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.
        - `type` 'logo', required
        - `request_id` string, uuid: Stable retry key. Requires item_id; reuse unchanged after an uncertain response.
        - `logo_style_id` 'graphic-app-icon' | 'cut-paper' | 'soft-depth' | 'geometric' | 'abstract-symbol' | 'monoline-symbol' | 'negative-space' | 'retro-emblem' | 'hand-drawn': Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields.
        - `logo_description` string: What the logo should look like, e.g. "iconic face-only, circular badge". Defaults to "Iconic representation of the character".
        - `logo_style_name` string: Short label for the logo style, e.g. "Flat", "Retro". Defaults to "Flat".
        - `logo_style_instruction` string: Detailed style instructions, e.g. "Flat design with solid colors, no gradients".
      - StudioGenerateSceneBody: Generate a 4K scene image of the mascot in an environment, or edit an existing scene. Cost: 3 credits.
        - `variant_id` string, uuid: Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.
        - `name` string: Name for the new item. Required when creating a new item. Omit when passing item_id.
        - `item_id` string, uuid: Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.
        - `type` 'scene', required
        - `source_asset_id` string, uuid: For a new scene: completed character image to use as its reference. Its saved variant context is retained unless an explicitly selected variant intentionally includes this reference. Use source_image_asset_id instead to edit an existing scene.
        - `scene` string: The environment, e.g. "cozy reading nook with afternoon light". Required unless editing (source_image_asset_id + edit_instructions).
        - `action` string: What the mascot is doing in the scene, e.g. "reading a book". Required unless editing.
        - `aspect_ratio` '4:3' | '1:1' | '21:9' | '4:5' | '3:4' | '9:16': Output aspect ratio. Use 4:3 for marketplace_card or marketplace_story, 1:1 for marketplace_square, 21:9 for hero_desktop, and 4:5 or 3:4 for hero_mobile.
        - `position` 'left' | 'center' | 'right': Where the mascot sits in the frame. Defaults: right for 21:9, center for others.
        - `source_image_asset_id` string, uuid: For scene edits: existing scene asset to edit. Must be paired with edit_instructions.
        - `edit_instructions` string: For scene edits: what to change, e.g. "warm up the lighting". Paired with source_image_asset_id.

## Response `202`

Batch generation jobs started

- BatchAsyncResponse
  - `data` BatchAsyncData, required
    - `jobs` GenerateAsyncData[], required
      - `job_id` string, uuid, required
      - `status` 'pending' | 'processing' | 'completed' | 'failed', required
      - `type` 'image' | 'animation' | 'edit' | 'logo' | 'reverse', required
      - `item_id` string, uuid, required
      - `item_name` string, required
      - `estimated_cost` number, required
      - `asset_ids` object
      - `urls` object
      - `estimate` TalkingEstimate: Talking animations only.
        - `speech_seconds` number, required: Estimated length of the spoken line.
        - `duration` integer, required: Most likely video length in seconds.
        - `max_duration` integer, required: The longest the video could need; the charge is based on it.
        - `credits` integer, required: Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.
        - `too_long` boolean, required
      - `script` string: Talking animations only: the line with its movements, as performed.
      - `poll_url` string, required
    - `total_cost` number, required
    - `poll_url` string, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `402`: Insufficient credits
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/91eb3006a92f?raw)