Make your mascot talk

Give your mascot a voice, write a line with its movements in brackets, and get a transparent talking video with the sound inside.

15 min · 1 credit for voices, 2 credits per second of talk · Studio or API

Do it in Studio#

1. Open your mascot in Studio, then Context & References. In the Voice row, press Add a voice.
2. Describe the voice (age, energy, pitch, accent) in the field named after your mascot, such as Describe Felix's voice. Press Hear 3 voices · 1 credit, then Keep on the one you like.
3. In the Animations tab, press Create Animation, then Talking animation.
4. Write the line in the What Felix says field, with movements in brackets where they start: [waves hello, excited] Hi! I'm Felix. Add movements writes them for you.
5. Pick the pose it Starts from and, optionally, the one it Ends on.
6. Check Estimated cost and press Generate · up to N credits. Unused seconds come back once the voice is recorded.

Do it with the API#

You need a write key from API keys in MASKO_API_KEY, your MASCOT_ID and an ITEM_ID to start from, such as "Waving hello" from Make it move. Under $50 spent, the voice calls in steps 1 to 3 return 403 with details.reason: "voice_locked", paid_cents and required_cents.

1. Get voice ideas#

Free voice descriptions written from your mascot's references; refresh=true gives others.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/voice/suggestions \
  -H "Authorization: Bearer $MASKO_API_KEY"

2. Hear three samples#

Three voices from one description, each reading the same optional sample_line. Samples expire after 24 hours (expires_at).

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/voice/samples \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A cheerful young fox. Young male voice, warm and bouncy, quick and friendly. American accent."
  }'

Listen to each url and note the id you like.

3. Keep one#

curl -X PUT https://api.masko.ai/v1/mascots/MASCOT_ID/voice \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sample_id": "SAMPLE_ID" }'

It replaces the mascot's voice, and variants without their own voice use it too. GET /v1/mascots/:id/voice shows it: source is original, or creator for a Marketplace mascot.

4. Write the line#

Bracketed words are never spoken, and a feeling after a comma steers the voice.

[waves hello, excited] Hi! I'm Felix. [points to the right] Your recipes are right here!

Or send only the words as speech.text, with an optional speech.direction, and Masko writes the movements. Set speech.language (such as fr), or leave it out to detect it.

5. Get the free estimate#

dry_run: true returns the length and price without charging. In shell, '\'' writes an apostrophe inside single quotes.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "item_id": "ITEM_ID",
    "speech": {
      "script": "[waves hello, excited] Hi! I'\''m Felix. [points to the right] Your recipes are right here!"
    },
    "dry_run": true
  }'

6. Generate it#

The same request without dry_run, plus an Idempotency-Key so a retry is never charged twice.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: felix-hello-001" \
  -d '{
    "type": "animation",
    "item_id": "ITEM_ID",
    "speech": {
      "script": "[waves hello, excited] Hi! I'\''m Felix. [points to the right] Your recipes are right here!"
    }
  }'

You pay for estimate.max_duration, minus the unused seconds once the voice is recorded; the job's cost_credits shows the final price. A mascot without a voice returns 409 with details.reason: "voice_required", before any charge.

Wait for the job#

Long-poll until completed or failed, or use a webhook.

curl "https://api.masko.ai/v1/jobs/JOB_ID?wait=true&timeout=120" \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

Never resend the generate request to check progress: without the same Idempotency-Key, it charges a second talk.

What you get#

Read the transcript with GET /v1/assets/{id}, then its file_url. Each line ends at ., ! or ?, ready for captions.

{
  "text": "Hi! I'm Felix. Your recipes are right here!",
  "language": "en",
  "duration": 6,
  "words": [{ "text": "Hi!", "start": 0.26, "end": 0.6 }],
  "lines": [{ "text": "Hi! I'm Felix.", "start": 0.26, "end": 1.5 }],
  "movements": [{ "text": "waves hello, excited", "start": 0.26, "end": 2.04 }]
}

Browsers block autoplay with sound: start the clip muted and unmute it on a tap.

Limits. A talk lasts 5 seconds to 5 minutes, following the speech, and uses the Standard model. It cannot go through generate-batch or be reversed or edited: send the script again for a new take. Long talks are cut at pauses into takes.

Using an AI agent?#

Voice and talking run through the REST API, so use an agent with the Masko skill and MASKO_API_KEY.

Make my Masko mascot talk by following
https://masko.ai/docs/tutorials/make-it-talk
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.
Use my mascot "MASCOT_NAME". If it has no voice, suggest voices, get three
samples (1 credit) and let me pick one before you keep it.
The line: "<what the mascot should say>". Write the movements in brackets.
Run a dry_run first, tell me the credits and wait for my OK.
Wait for the job without sending the request again, then give me the WebM,
HEVC and transcript links.

Next#