Docs curl quickstart

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#

  1. POST /images/generate twice → two portrait imageUrls.
  2. GET /voices → pick a voice id for each character.
  3. POST /avatars twice → a host avatar and a guest avatar. Save both avatarIds.
  4. POST /conversations with the host avatar → save conversationId + liveUrl.
  5. 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"
  }'
  1. Open or embed the liveUrl to watch each turn render in order.

Gotchas#

  • Turns are async. The 202 is a pending shell; audio/video URLs land on the turn doc as workers finish. Poll GET /conversations/by-slug/{shareSlug} every ~2s — or skip polling entirely and just show the liveUrl.
  • userText max 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 /live player, and polling only the returned turn id looks like silent truncation. Keep verbatim speak turns 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, use POST /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 liveUrl carries a ?token= capability, so treat it as a secret. POST /conversations/{id}/visibility {"isPublic":true} gets a clean tokenless URL.
  • POST /videos/generate is not lip-sync — for the avatar saying a line to camera with the mouth matching, use a speak turn as above. Use /videos/generate for 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.
  • 402 means not enough credits (response includes requiredCredits/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

Reading this as an AI assistant, or want to hand it to one? The same guide is plain markdown at masky.ai/masky-cli.md.