@gobi-ai/cli 0.9.7 → 0.9.9

package/.claude-plugin/marketplace.json

@@ -4,12 +4,12 @@
     "name": "gobi-ai"
   },
   "description": "Claude Code plugin for the Gobi collaborative knowledge platform CLI",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "plugins": [
     {
       "name": "gobi",
       "description": "Manage the Gobi collaborative knowledge platform from the command line. Search and ask brains, publish brain documents, create threads, manage sessions, generate images and videos.",
-      "version": "0.9.7",
+      "version": "0.9.9",
       "author": {
         "name": "gobi-ai"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gobi",
   "description": "Manage the Gobi collaborative knowledge platform from the command line",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "author": {
     "name": "gobi-ai"
   },

package/dist/commands/media.js

@@ -19,6 +19,48 @@ async function pollStatus(path, terminalStates, intervalMs = 3000) {
     }
     throw new Error(`Polling timed out after ${POLL_MAX_DURATION_MS / 1000}s`);
 }
+/**
+ * Download a video binary from the media-gen download endpoint.
+ * Handles three cases:
+ *   1. Direct binary response (redirect: "follow" returns the file)
+ *   2. JSON response with downloadUrl (need to fetch that URL)
+ *   3. Redirect (302) with Location header
+ */
+async function downloadVideoToFile(videoId, outputPath) {
+    const { writeFile, mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    const token = await getValidToken();
+    const dlUrl = `${BASE_URL}/media-gen/videos/${videoId}/download`;
+    // Try following redirects first
+    const res = await fetch(dlUrl, {
+        headers: { Authorization: `Bearer ${token}` },
+        redirect: "follow",
+    });
+    if (!res.ok) {
+        throw new ApiError(res.status, `/media-gen/videos/${videoId}/download`, await res.text());
+    }
+    const ct = res.headers.get("content-type") || "";
+    // If the response is JSON, extract downloadUrl and fetch the actual binary
+    if (ct.includes("application/json")) {
+        const json = (await res.json());
+        const inner = (json.data || json);
+        const url = (inner.downloadUrl || inner.download_url || inner.url);
+        if (!url)
+            throw new Error("Download endpoint returned JSON without a downloadUrl");
+        const videoRes = await fetch(url);
+        if (!videoRes.ok)
+            throw new Error(`Failed to fetch video from ${url}: ${videoRes.status}`);
+        const buffer = Buffer.from(await videoRes.arrayBuffer());
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, buffer);
+        return { contentType: videoRes.headers.get("content-type") || "video/mp4", size: buffer.length };
+    }
+    // Direct binary response
+    const buffer = Buffer.from(await res.arrayBuffer());
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, buffer);
+    return { contentType: ct || "video/mp4", size: buffer.length };
+}
 function extractImageUrl(data) {
     return (data.downloadUrl || data.download_url || data.url);
 }
@@ -136,56 +178,22 @@ export function registerMediaCommand(program) {
             body.backgroundMediaId = opts.backgroundMediaId;
         const resp = (await apiPost("/media-gen/videos", body));
         let data = unwrapResp(resp);
-        const videoId = data.id || data.videoId;
+        const videoId = data.id || data.videoId || data.jobId;
         if (shouldWait && videoId) {
             console.log(`Video ${videoId} queued — polling for completion…`);
             data = await pollStatus(`/media-gen/videos/${videoId}/status`, ["inference_complete", "inference_failed"]);
         }
+        // After polling, the status response may contain the real videoId for download
+        const downloadId = data.videoId || data.id || videoId;
         // Download video to file if -o specified
-        if (opts.output && videoId && data.status === "inference_complete") {
-            const token = await getValidToken();
-            const dlUrl = `${BASE_URL}/media-gen/videos/${videoId}/download`;
-            const dlRes = await fetch(dlUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "follow",
-            });
-            if (dlRes.ok) {
-                const { writeFile, mkdir } = await import("fs/promises");
-                const { dirname } = await import("path");
-                const buffer = Buffer.from(await dlRes.arrayBuffer());
-                await mkdir(dirname(opts.output), { recursive: true });
-                await writeFile(opts.output, buffer);
-                const contentType = dlRes.headers.get("content-type") || "video/mp4";
-                if (isJsonMode(media)) {
-                    jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                    return;
-                }
-                console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
+        if (opts.output && downloadId && data.status === "inference_complete") {
+            const { contentType, size } = await downloadVideoToFile(downloadId, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ ...data, filename: opts.output, contentType, size });
                 return;
             }
-            // If direct download fails, try getting the URL and fetching that
-            const dlRes2 = await fetch(dlUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "manual",
-            });
-            const location = dlRes2.headers.get("location");
-            if (location) {
-                const videoRes = await fetch(location);
-                if (videoRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await videoRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
-                    return;
-                }
-            }
+            console.log(`Video saved to ${opts.output} (${size} bytes)`);
+            return;
         }
         if (isJsonMode(media)) {
             jsonOut(data);
@@ -193,10 +201,10 @@ export function registerMediaCommand(program) {
         }
         const status = data.status || "queued";
         console.log(`Video created!\n` +
-            `  ID:     ${videoId}\n` +
+            `  ID:     ${downloadId}\n` +
             `  Status: ${status}`);
         if (status === "inference_complete") {
-            console.log(`  Download: gobi media video-download ${videoId}`);
+            console.log(`  Download: gobi media video-download ${downloadId}`);
         }
     });
     media
@@ -244,49 +252,14 @@ export function registerMediaCommand(program) {
             const data = await pollStatus(`/media-gen/videos/${id}/status`, ["inference_complete", "inference_failed"]);
             // Download if -o specified and completed
             if (opts.output && data.status === "inference_complete") {
-                const token = await getValidToken();
-                const dlUrl = `${BASE_URL}/media-gen/videos/${id}/download`;
-                const dlRes = await fetch(dlUrl, {
-                    headers: { Authorization: `Bearer ${token}` },
-                    redirect: "follow",
-                });
-                if (dlRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await dlRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = dlRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${buffer.length} bytes)`);
+                const dlId = (data.videoId || data.id || id);
+                const { contentType, size } = await downloadVideoToFile(dlId, opts.output);
+                if (isJsonMode(media)) {
+                    jsonOut({ ...data, filename: opts.output, contentType, size });
                     return;
                 }
-                // Try manual redirect
-                const dlRes2 = await fetch(dlUrl, {
-                    headers: { Authorization: `Bearer ${token}` },
-                    redirect: "manual",
-                });
-                const location = dlRes2.headers.get("location");
-                if (location) {
-                    const videoRes = await fetch(location);
-                    if (videoRes.ok) {
-                        const { writeFile, mkdir } = await import("fs/promises");
-                        const { dirname } = await import("path");
-                        const buffer = Buffer.from(await videoRes.arrayBuffer());
-                        await mkdir(dirname(opts.output), { recursive: true });
-                        await writeFile(opts.output, buffer);
-                        const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                        if (isJsonMode(media)) {
-                            jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                            return;
-                        }
-                        console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${buffer.length} bytes)`);
-                        return;
-                    }
-                }
+                console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${size} bytes)`);
+                return;
             }
             if (isJsonMode(media)) {
                 jsonOut(data);
@@ -312,48 +285,13 @@ export function registerMediaCommand(program) {
         const url = `${BASE_URL}/media-gen/videos/${id}/download`;
         // If -o specified, download directly to file
         if (opts.output) {
-            const res = await fetch(url, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "follow",
-            });
-            if (res.ok) {
-                const { writeFile, mkdir } = await import("fs/promises");
-                const { dirname } = await import("path");
-                const buffer = Buffer.from(await res.arrayBuffer());
-                await mkdir(dirname(opts.output), { recursive: true });
-                await writeFile(opts.output, buffer);
-                const contentType = res.headers.get("content-type") || "video/mp4";
-                if (isJsonMode(media)) {
-                    jsonOut({ filename: opts.output, contentType, size: buffer.length });
-                    return;
-                }
-                console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
+            const { contentType, size } = await downloadVideoToFile(id, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ filename: opts.output, contentType, size });
                 return;
             }
-            // If direct follow didn't work, try manual redirect
-            const res2 = await fetch(url, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "manual",
-            });
-            const location = res2.headers.get("location");
-            if (location) {
-                const videoRes = await fetch(location);
-                if (videoRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await videoRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
-                    return;
-                }
-            }
-            throw new ApiError(res.status, `/media-gen/videos/${id}/download`, "Failed to download video");
+            console.log(`Video saved to ${opts.output} (${size} bytes)`);
+            return;
         }
         // No -o: just return the URL (existing behavior)
         const res = await fetch(url, {
@@ -384,6 +322,221 @@ export function registerMediaCommand(program) {
         console.log(`Download URL for video ${id}:\n  ${data.url || data.downloadUrl || JSON.stringify(data)}`);
     });
     // ════════════════════════════════════════════════════════════════════
+    //  Cinematic Video
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("cinematic-create")
+        .description("Create a cinematic video from a text prompt.")
+        .requiredOption("--prompt <prompt>", "Text prompt describing the video")
+        .option("--name <name>", "Name for the video (auto-generated if omitted)")
+        .option("--aspect-ratio <aspectRatio>", "Aspect ratio: 16:9, 9:16, 1:1")
+        .option("--duration <seconds>", "Duration in seconds (4-8)")
+        .option("--resolution <resolution>", "Resolution: 720p, 1080p")
+        .option("--enhance-prompt", "Enhance the prompt with AI")
+        .option("--generate-audio", "Generate audio for the video")
+        .option("--negative-prompt <negativePrompt>", "Negative prompt")
+        .option("--sample-count <count>", "Number of samples (1-4)")
+        .option("--first-frame-media-id <mediaId>", "First frame image media ID")
+        .option("--last-frame-media-id <mediaId>", "Last frame image media ID")
+        .option("--reference-media-ids <ids>", "Comma-separated reference image media IDs (max 3)")
+        .option("--wait", "Poll until generation completes")
+        .option("-o, --output <path>", "Download video to this path when done (implies --wait)")
+        .action(async (opts) => {
+        const shouldWait = opts.wait || !!opts.output;
+        const autoName = opts.name || `cinematic-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
+        const body = {
+            name: autoName,
+            prompt: opts.prompt,
+        };
+        if (opts.aspectRatio)
+            body.aspectRatio = opts.aspectRatio;
+        if (opts.duration) {
+            const v = parseInt(opts.duration, 10);
+            if (Number.isNaN(v))
+                throw new Error("--duration must be a number");
+            body.durationSeconds = v;
+        }
+        if (opts.resolution)
+            body.resolution = opts.resolution;
+        if (opts.enhancePrompt)
+            body.enhancePrompt = true;
+        if (opts.generateAudio)
+            body.generateAudio = true;
+        if (opts.negativePrompt)
+            body.negativePrompt = opts.negativePrompt;
+        if (opts.sampleCount) {
+            const v = parseInt(opts.sampleCount, 10);
+            if (Number.isNaN(v))
+                throw new Error("--sample-count must be a number");
+            body.sampleCount = v;
+        }
+        if (opts.firstFrameMediaId)
+            body.firstFrameImageMediaId = opts.firstFrameMediaId;
+        if (opts.lastFrameMediaId)
+            body.lastFrameImageMediaId = opts.lastFrameMediaId;
+        if (opts.referenceMediaIds)
+            body.referenceImageMediaIds = opts.referenceMediaIds.split(",").map((s) => s.trim());
+        const resp = (await apiPost("/media-gen/videos/cinematic", body));
+        let data = unwrapResp(resp);
+        const videoId = data.id || data.videoId || data.jobId;
+        if (shouldWait && videoId) {
+            console.log(`Cinematic video ${videoId} queued — polling for completion…`);
+            data = await pollStatus(`/media-gen/videos/${videoId}/status`, ["inference_complete", "inference_failed"]);
+        }
+        // After polling, the status response may contain the real videoId for download
+        const downloadId = data.videoId || data.id || videoId;
+        // Download video to file if -o specified
+        if (opts.output && downloadId && data.status === "inference_complete") {
+            const { contentType, size } = await downloadVideoToFile(downloadId, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ ...data, filename: opts.output, contentType, size });
+                return;
+            }
+            console.log(`Cinematic video saved to ${opts.output} (${size} bytes)`);
+            return;
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const status = data.status || "queued";
+        console.log(`Cinematic video created!\n` +
+            `  ID:     ${downloadId}\n` +
+            `  Status: ${status}`);
+        if (status === "inference_complete") {
+            console.log(`  Download: gobi media video-download ${downloadId}`);
+        }
+    });
+    // ════════════════════════════════════════════════════════════════════
+    //  Custom Avatars
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("avatar-design")
+        .description("Start a design-your-avatar job.")
+        .requiredOption("--name <name>", "Name for the avatar")
+        .requiredOption("--gender <gender>", "Gender for the avatar design")
+        .requiredOption("--age <age>", "Age range for the avatar")
+        .requiredOption("--ethnicity <ethnicity>", "Ethnicity for the avatar")
+        .requiredOption("--outfit <outfit>", "Outfit description")
+        .requiredOption("--background <background>", "Background description")
+        .option("--no-portrait", "Generate full-body instead of portrait")
+        .option("--audio-media-id <mediaId>", "Custom voice audio media ID")
+        .option("--wait", "Poll until variants are ready")
+        .action(async (opts) => {
+        const body = {
+            name: opts.name,
+            gender: opts.gender,
+            age: opts.age,
+            ethnicity: opts.ethnicity,
+            outfit: opts.outfit,
+            background: opts.background,
+            isPortrait: opts.portrait,
+        };
+        if (opts.audioMediaId)
+            body.audioMediaId = opts.audioMediaId;
+        const resp = (await apiPost("/media-gen/avatars/design", body));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        if (opts.wait && jobId) {
+            console.log(`Avatar design job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const status = data.status || "queued";
+        console.log(`Avatar design started!\n` +
+            `  Job ID: ${jobId}\n` +
+            `  Status: ${status}`);
+        if (status === "variants_ready") {
+            console.log(`  Confirm: gobi media avatar-confirm --job-id ${jobId}`);
+        }
+    });
+    media
+        .command("avatar-confirm")
+        .description("Confirm avatar variant(s) after design.")
+        .requiredOption("--job-id <jobId>", "Job ID from avatar-design")
+        .option("--variant <variant>", "Variant to confirm (1 or 2); omit to confirm both")
+        .action(async (opts) => {
+        const body = { jobId: opts.jobId };
+        if (opts.variant) {
+            const v = parseInt(opts.variant, 10);
+            if (Number.isNaN(v))
+                throw new Error("--variant must be a number (1 or 2)");
+            body.variant = v;
+        }
+        const resp = (await apiPost("/media-gen/avatars/confirm", body));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const avatarId = data.avatarId || data.id;
+        console.log(`Avatar confirmed!\n` +
+            `  Avatar ID: ${avatarId || JSON.stringify(data)}`);
+    });
+    media
+        .command("avatar-from-selfie")
+        .description("Create an avatar from a selfie (instant or enhanced with prompt).")
+        .requiredOption("--name <name>", "Name for the avatar")
+        .requiredOption("--photo-media-id <mediaId>", "Selfie photo media ID")
+        .option("--prompt <prompt>", "Enhancement prompt (triggers async enhance flow)")
+        .option("--audio-media-id <mediaId>", "Custom voice audio media ID")
+        .option("--wait", "Poll until job completes (only for enhance flow)")
+        .action(async (opts) => {
+        const body = {
+            name: opts.name,
+            photoMediaId: opts.photoMediaId,
+        };
+        if (opts.prompt)
+            body.prompt = opts.prompt;
+        if (opts.audioMediaId)
+            body.audioMediaId = opts.audioMediaId;
+        const resp = (await apiPost("/media-gen/avatars/from-selfie", body));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        // Enhance flow is async — poll if --wait
+        if (opts.wait && opts.prompt && jobId) {
+            console.log(`Avatar enhance job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        if (opts.prompt) {
+            const status = data.status || "queued";
+            console.log(`Avatar enhance started!\n` +
+                `  Job ID: ${jobId}\n` +
+                `  Status: ${status}`);
+        }
+        else {
+            const avatarId = data.avatarId || data.id;
+            console.log(`Avatar created from selfie!\n` +
+                `  Avatar ID: ${avatarId || JSON.stringify(data)}`);
+        }
+    });
+    media
+        .command("avatar-job-status <jobId>")
+        .description("Check avatar job status.")
+        .option("--wait", "Poll until a terminal state is reached")
+        .action(async (jobId, opts) => {
+        let data;
+        if (opts.wait) {
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        else {
+            const resp = (await apiGet(`/media-gen/avatars/jobs/${jobId}/status`));
+            data = unwrapResp(resp);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Avatar job ${jobId} — status: ${data.status || "unknown"}`);
+    });
+    // ════════════════════════════════════════════════════════════════════
     //  Images
     // ════════════════════════════════════════════════════════════════════
     media

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobi-ai/cli",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "CLI client for the Gobi collaborative knowledge platform",
   "license": "MIT",
   "type": "module",

package/skills/gobi-media/SKILL.md

@@ -3,8 +3,10 @@ name: gobi-media
 description: >-
   Gobi media generation: generate images from text prompts (thumbnails,
   assets, logos), edit and inpaint images, create avatar videos with voice
-  narration, list available avatars and voices, upload media files. Use when
-  the user wants to generate images, create videos, or manage media.
+  narration, create cinematic videos from prompts, design custom avatars or
+  create avatars from selfies, list available avatars and voices, upload
+  media files. Use when the user wants to generate images, create videos,
+  or manage media.
 allowed-tools: Bash(gobi:*)
 metadata:
   author: gobi-ai
@@ -30,10 +32,11 @@ gobi --json media image-generate --prompt "a sunset over mountains"
 Single command — generate and download in one step:
 
 ```bash
-gobi --json media image-generate --prompt "<PROMPT>" -o media/<NAME>.png
+gobi --json media image-generate --prompt "<PROMPT>" --aspect-ratio "<RATIO>" -o media/<NAME>.png
 ```
 
 Replace `<NAME>` with a short descriptive slug derived from the prompt (e.g., `happy-family`, `sunset-mountains`).
+Replace `<RATIO>` with the desired aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, or `3:4`. Use `9:16` for Shorts/Reels.
 
 The `-o` flag implies `--wait` and downloads the image when done.
 
@@ -64,18 +67,56 @@ gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>"
 
 The `-o` flag implies `--wait` and downloads the video when done.
 
-**IMPORTANT: Avatars are pre-built system avatars ONLY.** You CANNOT create custom avatars from uploaded images. The `gobi media avatars` list is the complete set of available avatars. Do NOT attempt to upload an image and use its mediaId as an avatarId — it will fail.
+To use a custom image as the **background** of a video, upload it via `upload-init` / `upload-finalize`, then pass the mediaId as `--background-media-id`:
 
-To use a custom image (e.g. a generated image) as the **background** of a video, upload it first via `upload-init` / `upload-finalize`, then pass the mediaId as `--background-media-id`:
+```bash
+gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>" --script "<SCRIPT>" --background-media-id "<MEDIA_ID>" -o media/<NAME>.mp4
+```
+
+## Typical Workflow (Cinematic Video)
+
+Generate a cinematic video from a text prompt (no avatar needed):
 
 ```bash
-# 1. Upload custom image as background
-gobi --json media upload-init --file-name "bg.png" --content-type "image/png" --file-size <SIZE>
-curl -T "media/bg.png" -H "Content-Type: image/png" "<UPLOAD_URL>"
-gobi --json media upload-finalize --media-id "<MEDIA_ID>"
+gobi --json media cinematic-create --prompt "<PROMPT>" --aspect-ratio "<RATIO>" -o media/<NAME>.mp4
+```
 
-# 2. Create video with pre-built avatar + custom background
-gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>" --script "<SCRIPT>" --background-media-id "<MEDIA_ID>" -o media/<NAME>.mp4
+Options: `--duration <4-8>`, `--resolution <720p|1080p>`, `--enhance-prompt`, `--generate-audio`, `--negative-prompt`, `--sample-count <1-4>`, `--first-frame-media-id`, `--last-frame-media-id`, `--reference-media-ids`.
+
+## Custom Avatars
+
+Three ways to create custom avatars:
+
+### 1. Design from scratch
+
+```bash
+gobi --json media avatar-design --name "<NAME>" --gender "<GENDER>" --age "<AGE>" --ethnicity "<ETHNICITY>" --outfit "<OUTFIT>" --background "<BACKGROUND>" --wait
+```
+
+When `variants_ready`, confirm with:
+
+```bash
+gobi --json media avatar-confirm --job-id "<JOB_ID>"
+```
+
+### 2. From a selfie (instant)
+
+```bash
+gobi --json media avatar-from-selfie --name "<NAME>" --photo-media-id "<MEDIA_ID>"
+```
+
+Upload the selfie first via `upload-init` / `upload-finalize` to get the media ID.
+
+### 3. From a selfie (enhanced with prompt)
+
+```bash
+gobi --json media avatar-from-selfie --name "<NAME>" --photo-media-id "<MEDIA_ID>" --prompt "<ENHANCEMENT>" --wait
+```
+
+Check any avatar job status with:
+
+```bash
+gobi --json media avatar-job-status <jobId> --wait
 ```
 
 **IMPORTANT: After downloading, show the video using Obsidian wiki-link syntax EXACTLY like this:**
@@ -101,11 +142,19 @@ Do NOT use markdown image/link syntax `![](...)` or `gobi://` URLs. Always use `
 ### Videos
 
 - `gobi media video-create` — Create an avatar video generation job.
+- `gobi media cinematic-create` — Create a cinematic video from a text prompt.
 - `gobi media video-list` — List all videos.
 - `gobi media video-get` — Get video metadata.
 - `gobi media video-status` — Poll video generation status.
 - `gobi media video-download` — Download a completed video (`-o` to save to file).
 
+### Custom Avatars
+
+- `gobi media avatar-design` — Start a design-your-avatar job.
+- `gobi media avatar-confirm` — Confirm avatar variant(s) after design.
+- `gobi media avatar-from-selfie` — Create an avatar from a selfie (instant or enhanced).
+- `gobi media avatar-job-status` — Check avatar job status.
+
 ### Images
 
 - `gobi media image-generate` — Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4

package/skills/gobi-media/references/media.md

@@ -6,24 +6,29 @@ Usage: gobi media [options] [command]
 Media generation commands (videos, images).
 
 Options:
-  -h, --help                        display help for command
+  -h, --help                           display help for command
 
 Commands:
-  upload-init [options]             Get a presigned upload URL for a media file.
-  upload-finalize [options]         Confirm that a media upload is complete.
-  avatars                           List available avatars.
-  voices                            List available voices.
-  video-create [options]            Create an avatar video generation job.
-  video-list                        List all videos.
-  video-get <id>                    Get video metadata.
-  video-status [options] <id>       Poll video generation status.
-  video-download [options] <id>     Download a completed video (or get its URL).
-  image-generate [options]          Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
-  image-edit [options]              Edit an existing image with a prompt (image-to-image).
-  image-inpaint [options]           Inpaint an image region using a mask.
-  image-status [options] <jobId>    Check image generation job status.
-  image-download [options] <jobId>  Download a generated image.
-  help [command]                    display help for command
+  upload-init [options]                Get a presigned upload URL for a media file.
+  upload-finalize [options]            Confirm that a media upload is complete.
+  avatars                              List available avatars.
+  voices                               List available voices.
+  video-create [options]               Create an avatar video generation job.
+  video-list                           List all videos.
+  video-get <id>                       Get video metadata.
+  video-status [options] <id>          Poll video generation status.
+  video-download [options] <id>        Download a completed video (or get its URL).
+  cinematic-create [options]           Create a cinematic video from a text prompt.
+  avatar-design [options]              Start a design-your-avatar job.
+  avatar-confirm [options]             Confirm avatar variant(s) after design.
+  avatar-from-selfie [options]         Create an avatar from a selfie (instant or enhanced with prompt).
+  avatar-job-status [options] <jobId>  Check avatar job status.
+  image-generate [options]             Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+  image-edit [options]                 Edit an existing image with a prompt (image-to-image).
+  image-inpaint [options]              Inpaint an image region using a mask.
+  image-status [options] <jobId>       Check image generation job status.
+  image-download [options] <jobId>     Download a generated image.
+  help [command]                       display help for command
 ```
 
 ## upload-init
@@ -139,6 +144,92 @@ Options:
   -h, --help           display help for command
 ```
 
+## cinematic-create
+
+```
+Usage: gobi media cinematic-create [options]
+
+Create a cinematic video from a text prompt.
+
+Options:
+  --prompt <prompt>                   Text prompt describing the video
+  --name <name>                       Name for the video (auto-generated if omitted)
+  --aspect-ratio <aspectRatio>        Aspect ratio: 16:9, 9:16, 1:1
+  --duration <seconds>                Duration in seconds (4-8)
+  --resolution <resolution>           Resolution: 720p, 1080p
+  --enhance-prompt                    Enhance the prompt with AI
+  --generate-audio                    Generate audio for the video
+  --negative-prompt <negativePrompt>  Negative prompt
+  --sample-count <count>              Number of samples (1-4)
+  --first-frame-media-id <mediaId>    First frame image media ID
+  --last-frame-media-id <mediaId>     Last frame image media ID
+  --reference-media-ids <ids>         Comma-separated reference image media IDs (max 3)
+  --wait                              Poll until generation completes
+  -o, --output <path>                 Download video to this path when done (implies --wait)
+  -h, --help                          display help for command
+```
+
+## avatar-design
+
+```
+Usage: gobi media avatar-design [options]
+
+Start a design-your-avatar job.
+
+Options:
+  --name <name>               Name for the avatar
+  --gender <gender>           Gender for the avatar design
+  --age <age>                 Age range for the avatar
+  --ethnicity <ethnicity>     Ethnicity for the avatar
+  --outfit <outfit>           Outfit description
+  --background <background>   Background description
+  --no-portrait               Generate full-body instead of portrait
+  --audio-media-id <mediaId>  Custom voice audio media ID
+  --wait                      Poll until variants are ready
+  -h, --help                  display help for command
+```
+
+## avatar-confirm
+
+```
+Usage: gobi media avatar-confirm [options]
+
+Confirm avatar variant(s) after design.
+
+Options:
+  --job-id <jobId>     Job ID from avatar-design
+  --variant <variant>  Variant to confirm (1 or 2); omit to confirm both
+  -h, --help           display help for command
+```
+
+## avatar-from-selfie
+
+```
+Usage: gobi media avatar-from-selfie [options]
+
+Create an avatar from a selfie (instant or enhanced with prompt).
+
+Options:
+  --name <name>               Name for the avatar
+  --photo-media-id <mediaId>  Selfie photo media ID
+  --prompt <prompt>           Enhancement prompt (triggers async enhance flow)
+  --audio-media-id <mediaId>  Custom voice audio media ID
+  --wait                      Poll until job completes (only for enhance flow)
+  -h, --help                  display help for command
+```
+
+## avatar-job-status
+
+```
+Usage: gobi media avatar-job-status [options] <jobId>
+
+Check avatar job status.
+
+Options:
+  --wait      Poll until a terminal state is reached
+  -h, --help  display help for command
+```
+
 ## image-generate
 
 ```