Masky API keys are generated at https://masky.ai/docs. No key? See "First: get an API key" in https://masky.ai/skill.md — an AI assistant can connect its user's account with one link, no developer page needed.
Masky from the command line#
Drive Masky — the AI avatar platform — from any shell with curl. This is the quickstart: a first render end to end, a two-avatar podcast, and the gotchas that trip up scripts. Every endpoint, parameter, and error code lives in the full reference: https://masky.ai/masky-api.md.
Setup: export your key and verify it.
export MASKY_API_KEY=mky_...
curl -s https://masky.ai/api/avatars -H "Authorization: Bearer $MASKY_API_KEY"
# 200 -> key works; 401 -> invalid or revoked
Base URL is https://masky.ai/api; all bodies are JSON. Generation costs credits, billed to the avatar's owner, charged only on success.
First render — your avatar says a line on video#
# 1. Generate a portrait (synchronous, a few seconds)
curl -s -X POST https://masky.ai/api/images/generate \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"prompt":"photorealistic portrait of a friendly robot barista, studio light","aspectRatio":"1:1"}'
# -> { "imageUrl": "https://.../img.jpeg", ... }
# 2. Pick a voice
curl -s https://masky.ai/api/voices -H "Authorization: Bearer $MASKY_API_KEY"
# -> { "voices": [ { "id": "...", "name": "Deep Male Conversational Voice", ... } ] }
# 3. Create the avatar
curl -s -X POST https://masky.ai/api/avatars \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"displayName":"Barista Bot","imageUrl":"<imageUrl from step 1>","personalityPrompt":"You are a cheerful robot barista.","voiceId":"<voice id from step 2>"}'
# -> { "avatar": { "avatarId": "...", "avatarOwnerUserId": "...", ... } }
# 4. Start a conversation
curl -s -X POST https://masky.ai/api/conversations \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"avatarOwnerUserId":"<from step 3>","avatarId":"<from step 3>"}'
# -> { "conversationId": "...", "shareSlug": "c-26-...", "liveUrl": "https://masky.ai/live/c-26-...?token=..." }
# 5. Inject a verbatim "speak" turn (202 returns immediately; render is async)
curl -s -X POST https://masky.ai/api/conversations/<conversationId>/turn \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"userText":"Welcome in! One oat-milk flat white, coming right up.","mode":"speak","output":"video"}'
# -> { "turn": { "id": "...", "status": "pending", ... }, "async": true }
# 6. Poll until the turn's videoUrl is non-null (~30-60s; audio-only lands in ~5-10s)
curl -s "https://masky.ai/api/conversations/by-slug/<shareSlug>" -H "Authorization: Bearer $MASKY_API_KEY"
Hand back the conversation's liveUrl — it auto-plays each turn the moment it renders, with captions and player controls, and keeps working as you add turns. For one turn's own shareable player, read that turn's liveUrl (https://masky.ai/live/t-…) from the poll response.
Just want the video file, no realtime player? Skip the conversation and use the one-shot speak endpoint — one call, one unsplit clip (conversation replies get split into multiple short clips for live-playback latency):
curl -s -X POST https://masky.ai/api/avatars/<avatarId>/speak \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"text":"Welcome in! One oat-milk flat white, coming right up.","output":"video"}'
# 202 -> { "generationId": "...", ... }
curl -s https://masky.ai/api/avatars/speak/<generationId> -H "Authorization: Bearer $MASKY_API_KEY"
# poll until generation.status == "video" -> download generation.videoUrl
Bring your own audio — pass audioUrl instead of text (exactly one of the two) and the avatar lip-syncs YOUR MP3/WAV speech: sung vocals, a pre-recorded line, any voice, no TTS, no voice needed on the avatar. Works on both one-shot speak and a mode:"speak" conversation turn (always one unsplit clip). Max 3 minutes, billed on the measured duration, output must be audio/video:
curl -s -X POST https://masky.ai/api/avatars/<avatarId>/speak \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{"audioUrl":"https://example.com/verse-1.mp3","output":"video"}'
Worked example — a two-avatar podcast#
POST /images/generatetwice → two portraitimageUrls.GET /voices→ pick a voiceidfor each character.POST /avatarstwice → a host avatar and a guest avatar. Save bothavatarIds.POST /conversationswith the host avatar → saveconversationId+liveUrl.- For each exchange, script both sides in one call:
curl -s -X POST https://masky.ai/api/conversations/<conversationId>/turn \
-H "Authorization: Bearer $MASKY_API_KEY" -H "Content-Type: application/json" \
-d '{
"userText": "So sell me — what is this, in one breath?",
"avatarText": "An API that turns text into avatars who talk. This very podcast is the output.",
"speakerAvatarId": "<guest avatarId>",
"userOutput": "video",
"output": "video",
"mode": "chat"
}'
- Open or embed the
liveUrlto watch each turn render in order.
Gotchas#
- Turns are async. The
202is a pending shell; audio/video URLs land on the turn doc as workers finish. PollGET /conversations/by-slug/{shareSlug}every ~2s — or skip polling entirely and just show theliveUrl. userTextmax 500 chars (≈ ~35s of speech — the longest single clip), and every avatar reply in a conversation is auto-chunked into ≤3-sentence turns with their own ids — that split is a latency feature for the realtime/liveplayer, and polling only the returned turn id looks like silent truncation. Keep verbatimspeakturns to ≤3 sentences for a 1:1 turn↔clip mapping, read all turns from the conversation — or, when you don't need realtime playback at all, usePOST /avatars/{avatarId}/speak(above) for one unsplit clip per call.- Media URLs are signed, ~1h TTL and re-signed on every conversation read — don't cache them long.
- Conversations start private: the
liveUrlcarries a?token=capability, so treat it as a secret.POST /conversations/{id}/visibility {"isPublic":true}gets a clean tokenless URL. POST /videos/generateis not lip-sync — for the avatar saying a line to camera with the mouth matching, use aspeakturn as above. Use/videos/generatefor scenes, animated images, or the avatar in a shot with generated sound.- Voice delivery — speak/turn bodies take an optional
voiceStyle: { emotion, style, prosody: [] }(falls back per-field to the avatar's Voice-tab default), and spoken text may embed inline cues (<|sfx:laughter|>,<|prosody:pause|>; stripped from captions). An sfx tag must immediately precede matching onomatopoeia to vocalize —<|sfx:laughter|>Haha!laughs, a bare tag before ordinary words is silently skipped. Full vocabulary: the Voice delivery section of https://masky.ai/masky-api.md. 402means not enough credits (response includesrequiredCredits/availableCredits). Failures don't burn credits.
Everything else — image/video params and pricing, avatar image variants, folders, brain memory and sandboxes, translations (captions / dubbed audio / lip-synced video per language), the local-agent bridge — is in the full reference: https://masky.ai/masky-api.md. Adding "Login with Masky" sign-in to your own site (plus tribes & credit gifts): https://masky.ai/masky-sso.md.
Generate or manage your Masky API key any time at https://masky.ai/docs