---
title: "Generate image or animation"
method: POST
path: "/v1/mascots/{id}/generate"
tags: ["Generate"]
---

# Generate image or animation

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

## Request

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

Starts an async generation job. Returns 202 with `data.job_id` - poll via GET `/v1/jobs/{id}` (or pass `?wait=true` for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (2–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, scene=3, reverse=0. For `type: animation`, you can skip providing a source image: pass only `animation_prompt` (and optionally `image_prompt`) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass `item_id` to animate/edit its current image. For image generation and image edits, pass optional `visual_references` for one-time pose, expression, motion, prop, style, or scene cues; these references do not become mascot mascot references. Scene generation and scene editing also use this endpoint with `type: "scene"`. For a new scene, optional `source_asset_id` selects its character reference and saved variant context. For scene edits use `source_image_asset_id` with `edit_instructions`; the two source fields are mutually exclusive. Talking animations: pass `speech` with `type: animation` and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With `dry_run: true` it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- 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 `200`

Talking estimate (speech with dry_run)

- TalkingDryRunResponse
  - `data` object, required
    - `dry_run` true, required
    - `script` string, required
    - `estimate` TalkingEstimate, required: 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

## Other responses

- `202`: Generation job started
- `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/84832e255613?raw)