Skip to content
Masko logomasko
Docs
TerminalAPI reference
Documentation

End-to-end generation flow

This guide walks through the full path from zero to an animated mascot in a sequence of API calls: create a project and collection, add references, generate a pose image, then animate that pose. Each step feeds IDs into the next, so follow them in order.

Step 1: Create a project and collection

Projects are top-level containers. Each project holds one or more collections, and each collection represents one mascot character. Create the project first, then seed the collection with reference_image_urls so style extraction can kick off on the first generation.

curl -X POST https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SaaS"
  }'
curl -X POST https://api.masko.ai/v1/collections \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "75270a54-f2f9-58e5-83c0-8575c720ca86",
    "name": "Felix the Fox",
    "context": "Friendly brand mascot for our SaaS",
    "reference_image_urls": [
      "https://example.com/fox-front.png",
      "https://example.com/fox-side.png"
    ]
  }'

Step 2: Add additional references (optional)

If you want to add more reference images after creating the collection, use the references endpoint. Up to 6 references total. Adding or removing references clears the cached style card so the next generation re-extracts it.

curl -X POST https://api.masko.ai/v1/collections/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/references \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/fox-back.png"
  }'

See Reference images and style consistency for more on how references work.

Step 3: Generate a pose image

Now generate a static image of the mascot in the pose you want to animate. The response returns asset_ids.image, which is the ID you will need in step 4.

curl -X POST https://api.masko.ai/v1/collections/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/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"
  }'

Poll /v1/jobs/0818df65-d092-5901-a506-3b2e64fb88ef?wait=true until the job reaches completed. You can use the asset_ids.image returned by the generate response as source_image_asset_id in the next step.

Step 4: Animate that pose

Call the same /generate endpoint again with type: "animation" and set source_image_asset_id to the asset_ids.image value captured in step 3. The animation is built from that exact pose.

curl -X POST https://api.masko.ai/v1/collections/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "item_id": "b3bbee96-0599-5ca2-ab23-e7b157f50091",
    "source_image_asset_id": "3c8ce568-35ce-59c2-b3f8-9fb7e4a16e52",
    "animation_prompt": "waving arm back and forth in a friendly greeting",
    "duration": 4
  }'

Next steps