Sounds

A mascot can have its own sounds: a giggle, a squeal, a "Hm?", a word or two. Upload them from any audio file. An animation with sound plays one of them, and the mascot moves in time with it. When none fits, the video model makes a sound for it. The price is the animation's normal price.

1. Add the mascot's sounds

Send a public link, or upload the file. MP3, M4A/AAC, WAV, OGG, Opus, FLAC, AIFF and WebM all work, as does the sound of a video, up to 50 MB.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/sounds \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/yippee.m4a", "name": "Yippee"}'

To upload a file from your computer, ask for an upload link first with POST /v1/mascots/MASCOT_ID/sounds/uploads and {"file_name": "yippee.m4a", "content_type": "audio/mp4"}. PUT the file to upload_url with upload_headers, then send upload_id and the same file_name to POST /v1/mascots/MASCOT_ID/sounds.

Masko trims the silence around the sound and evens out its loudness. At most 10 seconds of sound remain. It measures the sound's bursts ("sneak, sneak" is two) and its loudest moment. It then listens to it for 15 to 60 seconds and writes down the words, a description, the feeling and the moments it fits.

2. Read them

{
  "data": {
    "sounds": [
      {
        "object": "sound",
        "name": "Yippee",
        "duration": 1.88,
        "parts": [
          { "start": 0, "end": 0.22, "peak": 0.17, "label": "yip" },
          { "start": 0.24, "end": 1.88, "peak": 0.9, "label": "pee" }
        ],
        "peak_at": 0.17,
        "listening": "heard",
        "words": "Yippee!",
        "description": "A very high-pitched, energetic voice shouts 'Yippee!' with great excitement.",
        "feeling": "joyful",
        "kind": "vocal",
        "fits": ["jumping for joy", "celebrating a win"]
      }
    ]
  }
}

Correct a description with PATCH /v1/mascots/MASCOT_ID/sounds/SOUND_ID and {"description": "..."}, since sound picking reads it. Remove a sound with DELETE. Animations already made keep their sound.

3. Animate with sound

Add "sound": true to an animation. It needs the standard model, a picture to start from, 5 to 15 seconds, and a loop or an end picture.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type": "animation", "item_id": "POSE_ITEM_ID", "animation_prompt": "jumps for joy and shouts yippee", "duration": 5, "sound": true}'

One of its sounds: a sound the prompt names or describes is used. Otherwise the one that clearly fits, if any. Its loudest moment lands on the key moment of the motion.
Otherwise, a sound made for it: the video model makes a sound that fits, unless the mascot only uses its own sounds. That setting is in the mascot's character page in Studio.
Never on calm loops: a calm idle loop gets no sound unless the prompt asks for one.

The receipt's sound says which sound was used, when it starts, and why. A finished animation has its sound in every file: MP4, transparent WebM and HEVC, and the files for the Masko player. Players play it unless the app turns sound off.

Through the MCP server, an agent reads the sounds with get_mascot, adds one from a link with update_mascot, and turns sound on with animate_mascot.

Sounds

1. Add the mascot's sounds#

2. Read them#

3. Animate with sound#

1. Add the mascot's sounds

2. Read them

3. Animate with sound