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](https://masky.ai) — 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.

```bash
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

```bash
# 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):

```bash
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`:

```bash
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 `imageUrl`s.
2. `GET /voices` → pick a voice `id` for each character.
3. `POST /avatars` twice → a host avatar and a guest avatar. Save both `avatarId`s.
4. `POST /conversations` with the **host** avatar → save `conversationId` + `liveUrl`.
5. For each exchange, script both sides in one call:

```bash
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"
  }'
```

6. 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
