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.

POST/v1/collections/:id/generate

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 collection with pending image and transparent_image assets.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_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/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "edit",
    "item_id": "item_def456",
    "source_image_asset_id": "ast_img_001",
    "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/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "item_id": "item_def456",
    "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 collection. 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.

Tip

If your character looks different across generations, add 2-3 reference images showing the character from different angles. The style card will recalculate automatically when references change.

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 and generate in a few seconds.

Use animations when you need movement - idle loops, transitions between states, reactions, or interactive behaviors. Animations start at 16 credits (3 seconds) and take longer to generate. See the Animations guide for details.