Create your first mascot

One sentence becomes your mascot's first reference image: the picture Masko reads before every new pose and animation, so the character keeps the same look.

5 min · 1 credit · Studio or API

Do it in Studio#

1. Open Create a mascot on the Create with AI tab.
2. Write one sentence in Describe your mascot, such as "A friendly orange fox with a blue scarf, for a cooking app". Stuck? Press Give me ideas.
3. Optional: pick a Style card and a few Design touches.
4. Press Generate · 1 credit. Each try appears under Your tries, and Generate another draws one more for 1 credit.
5. Click the try you like. To fix a detail, write it in Change something and press Refine · 1 credit.
6. Fill in Name your mascot and press Create mascot.

Do it with the API#

Create a key with write access in API keys. Run these calls on your server or in a terminal, never in browser code.

export MASKO_API_KEY=masko_YOUR_KEY

1. Create a project#

A project groups your mascots. It is free.

curl -X POST https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My App" }'

Save data.id as PROJECT_ID.

2. Create the mascot from a sentence#

Send a prompt with no reference images, and Masko draws the first reference for 1 credit, refunded if drawing or saving fails. A retry with the same Idempotency-Key and body is never charged twice.

curl -X POST https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-mascot-001" \
  -d '{
    "name": "Felix the Fox",
    "project_id": "PROJECT_ID",
    "prompt": "A friendly orange fox with a blue scarf, for a cooking app"
  }'

Save data.id as MASCOT_ID. Optional fields: style takes a preset ID from GET /v1/styles, and design_touches takes ideas such as ["proportions", "eyes-big", "mood-cozy"] (see create from text).

3. Look at the reference#

The asset's file_url is a signed link that expires, so keep the asset ID and read it again for a fresh link.

curl https://api.masko.ai/v1/assets/REFERENCE_ASSET_ID \
  -H "Authorization: Bearer $MASKO_API_KEY"

Optional: compare drafts before you choose#

Preview several takes at 1 credit each, then create the mascot from the one you like for no extra credits. Preview links expire after an hour (expires_in: 3600).

curl -X POST https://api.masko.ai/v1/generate/preview \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A friendly orange fox with a blue scarf, for a cooking app",
    "count": 4
  }'

Then send the chosen url to POST /v1/mascots as "reference_image_urls": ["URL_FROM_PREVIEW"], with name, project_id and the same prompt.

Is there a job to wait for?#

No. Creating a mascot answers once the reference is drawn, so the call takes a little while, but there is nothing to poll. Poses and animations return a job_id; the next tutorial shows how to wait for one.

What you get#

• A mascot with an id, a name and a slug. The slug becomes part of its hosted links, such as https://assets.masko.ai/{prefix}/felix-the-fox/....
• One reference image, a PNG. A mascot holds up to 6 references, and more angles give steadier results. See reference images.
• Hosting on by default for mascots created with the API (settings.cdn_enabled: true), so your next files get permanent links. Asset hosting is billed separately from credits.

Using an AI agent?#

Paste this into an agent connected to the Masko MCP server (setup for Claude Code, Codex, Cursor and more), or into one with the Masko skill and an API key.

Create my first Masko mascot by following
https://masko.ai/docs/tutorials/first-mascot
My product: <what it does and who it is for>.
Use the Masko MCP tools if they are connected. Otherwise use the REST API at
https://api.masko.ai/v1 with MASKO_API_KEY from my environment. Never print the
key or put it in browser code.
Before any paid call, tell me the credits and wait for my OK. It should be 1 credit.
When it is done, show me the reference image and give me the mascot ID.

Next#