Images & Poses

Generate static mascot images from text prompts. Each image costs 1 credit and produces both a full image and a transparent (background-removed) variant.

Generate an Image

Send a type: "image" request with a name for the item and an image_prompt describing the pose. A new item is created in your mascot with pending image and transparent_image assets.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "name": "Waving hello",
    "image_prompt": "waving hello with a friendly smile, one arm raised"
  }'

Edit an Image

Modify an existing image with natural language instructions. Pass type: "edit" along with source_image_asset_id and edit_instructions. The edit creates new assets on the same item. Costs 1 credit.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "edit",
    "item_id": "b3bbee96-0599-5ca2-ab23-e7b157f50091",
    "source_image_asset_id": "3c8ce568-35ce-59c2-b3f8-9fb7e4a16e52",
    "edit_instructions": "Add a party hat and confetti falling around"
  }'

Regenerate

To regenerate an existing item, pass the same item_id with a new image_prompt. The endpoint creates fresh assets under the same item each time. Previous assets remain accessible - nothing is overwritten.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "item_id": "b3bbee96-0599-5ca2-ab23-e7b157f50091",
    "image_prompt": "waving hello with both arms raised high"
  }'

Style Consistency

Masko keeps your mascot looking consistent across all generated images using two mechanisms:

• Reference images - Up to 6 images pinned as references in your mascot. Every generation includes these as visual context so the AI matches the character's appearance.
• Style card - Automatically extracted from your references on the first generation. The style card captures defining traits like color palette, proportions, and design style, then injects them into every prompt.

You do not need to configure either of these manually. Add reference images via the references endpoint, and the style card is generated lazily when you first run a generation.

Image vs Animation

Use images when you need a static pose - profile pictures, thumbnails, marketing assets, or any context where motion is not needed. Images cost 1 credit each.

Use animations when you need movement - idle loops, transitions between states, reactions, or interactive behaviors. Standard animations start at 10 credits (5 seconds from an existing image), plus 1 if a new source image is needed. Premium costs 6 credits per second. Set animation_model explicitly; omitting it keeps legacy pricing. Animations take longer to generate than images. See the Animations guide for details.