@remixmate/cli 0.9.55 → 0.9.57

package/dist/handlers/gen-digital-human.d.ts

@@ -1,12 +1,17 @@
 /**
- * gen-digital-human handler — talking-head video, three modes:
- *   --list-avatars true                  → POST /digital-human/avatar/page (list)
- *   --check-status --generation-id <id>  → POST /digital-human/video/status (one-shot)
- *   default (--avatar-id <id> ...)       → generate: resolve avatar → submit → poll
+ * gen-digital-human handler — talking-head video + custom avatars, five modes:
+ *   --list-avatars true                          → POST /digital-human/avatar/page (list)
+ *   --clone --clone-url <url> --name <n>         → POST /digital-human/avatar/clone, then poll clone-status
+ *   --clone-status --avatar-id <id>              → POST /digital-human/avatar/clone-status (one-shot)
+ *   --check-status --generation-id <id>          → POST /digital-human/video/status (one-shot)
+ *   default (--avatar-id <id> ...)               → generate: resolve avatar → submit → poll
  *
  * Ported from `scripts/gen_digital_human_video.py` (python → http) so it shares
  * auth / base-URL / business-code handling with the other generators via
- * http.ts. Endpoints and payloads match the backend DigitalHumanVideoGenerateDTO.
+ * http.ts. Endpoints and payloads match the backend DigitalHuman* DTOs.
+ *
+ * Avatar ids are the backend's opaque uids (`dh_...`); legacy numeric ids are
+ * still accepted as strings.
  */
 import type { HandlerContext, HandlerInput } from './index.js';
 export declare function genDigitalHuman(input: HandlerInput, ctxIn: HandlerContext): Promise<void>;

package/dist/handlers/gen-digital-human.js

@@ -1,21 +1,37 @@
 /**
- * gen-digital-human handler — talking-head video, three modes:
- *   --list-avatars true                  → POST /digital-human/avatar/page (list)
- *   --check-status --generation-id <id>  → POST /digital-human/video/status (one-shot)
- *   default (--avatar-id <id> ...)       → generate: resolve avatar → submit → poll
+ * gen-digital-human handler — talking-head video + custom avatars, five modes:
+ *   --list-avatars true                          → POST /digital-human/avatar/page (list)
+ *   --clone --clone-url <url> --name <n>         → POST /digital-human/avatar/clone, then poll clone-status
+ *   --clone-status --avatar-id <id>              → POST /digital-human/avatar/clone-status (one-shot)
+ *   --check-status --generation-id <id>          → POST /digital-human/video/status (one-shot)
+ *   default (--avatar-id <id> ...)               → generate: resolve avatar → submit → poll
  *
  * Ported from `scripts/gen_digital_human_video.py` (python → http) so it shares
  * auth / base-URL / business-code handling with the other generators via
- * http.ts. Endpoints and payloads match the backend DigitalHumanVideoGenerateDTO.
+ * http.ts. Endpoints and payloads match the backend DigitalHuman* DTOs.
+ *
+ * Avatar ids are the backend's opaque uids (`dh_...`); legacy numeric ids are
+ * still accepted as strings.
  */
 import { mmPost, pollUntil, resolveHttpContext, SkillError } from '../http.js';
 import { getCapabilities } from '../capabilities.js';
 import { emitProgress } from '../progress.js';
 import { isTrue, toNumber } from './shared.js';
+const CLONE_TYPES = ['video', 'image'];
+/**
+ * The only provider currently wired end to end (HiFly). HiFly's generate APIs
+ * take no aspect ratio or action prompt — the output keeps the cloned source's
+ * framing — so the handler sends neither.
+ */
+const ACTIVE_SOURCE = 'hifly';
+function toId(value) {
+    if (value === undefined || value === null)
+        return '';
+    return String(value).trim();
+}
 async function listAvatars(ctx, input) {
-    const payload = { current: 1, pageSize: 100 };
-    if (input.source)
-        payload.source = String(input.source);
+    // Only avatars of the active provider can be driven, so only those are listed.
+    const payload = { current: 1, pageSize: 100, source: ACTIVE_SOURCE };
     if (input.gender)
         payload.gender = String(input.gender);
     if (isTrue(input.mine))
@@ -32,31 +48,107 @@ async function listAvatars(ctx, input) {
         process.stdout.write('⚠️  No avatars available\n');
         return;
     }
-    process.stdout.write(`\n${'ID'.padEnd(8)} ${'Name'.padEnd(16)} ${'Source'.padEnd(10)} ${'Gender'.padEnd(8)} Ratio\n`);
-    process.stdout.write(`${'-'.repeat(8)} ${'-'.repeat(16)} ${'-'.repeat(10)} ${'-'.repeat(8)} ${'-'.repeat(10)}\n`);
+    process.stdout.write(`\n${'ID'.padEnd(24)} ${'Name'.padEnd(16)} ${'Source'.padEnd(14)} ${'Gender'.padEnd(8)} ${'Ratio'.padEnd(6)} Clone\n`);
+    process.stdout.write(`${'-'.repeat(24)} ${'-'.repeat(16)} ${'-'.repeat(14)} ${'-'.repeat(8)} ${'-'.repeat(6)} ${'-'.repeat(8)}\n`);
     for (const a of avatars) {
-        process.stdout.write(`${String(a.id ?? '').padEnd(8)} ${String(a.name ?? '').padEnd(16)} ${String(a.source ?? '').padEnd(10)} ${String(a.gender ?? '').padEnd(8)} ${a.aspectRatio ?? ''}\n`);
+        process.stdout.write(`${toId(a.id).padEnd(24)} ${String(a.name ?? '').padEnd(16)} ${String(a.source ?? '').padEnd(14)} ${String(a.gender ?? '').padEnd(8)} ${String(a.aspectRatio ?? '').padEnd(6)} ${a.cloneStatus || '-'}\n`);
     }
-    process.stdout.write(`\n${avatars.length} avatar(s) available\n`);
+    const total = data.pager?.total ?? avatars.length;
+    process.stdout.write(`\n${avatars.length} avatar(s) shown${total > avatars.length ? ` of ${total}; narrow with --name` : ''}\n`);
     process.stdout.write('💡 Use --avatar-id <ID> to pick an avatar for generation\n');
 }
-/** Look up one avatar's metadata; checks the normal page then `mine: true`. */
+/**
+ * Look up one avatar's metadata. Only the caller's own avatars are searched: they
+ * are few, and they are the only ones that can be mid-clone or failed. The public
+ * HiFly catalog has ~1000 entries, far beyond one page, so a public id that is not
+ * among "mine" is passed through as-is and the backend validates it (unknown ids
+ * come back as a business error).
+ */
 async function fetchAvatarInfo(ctx, avatarId) {
-    for (const extra of [{}, { mine: true }]) {
-        const data = await mmPost(ctx, '/digital-human/avatar/page', { current: 1, pageSize: 100, ...extra }, { timeoutMs: 30_000 });
-        const found = (data.list ?? []).find((a) => String(a.id) === String(avatarId));
-        if (found)
-            return found;
-    }
-    throw new SkillError(`❌ avatar_id=${avatarId} not found; use --list-avatars [--mine] to see what is available`);
+    const data = await mmPost(ctx, '/digital-human/avatar/page', { current: 1, pageSize: 100, mine: true, source: ACTIVE_SOURCE }, { timeoutMs: 30_000 });
+    const found = (data.list ?? []).find((a) => toId(a.id) === avatarId);
+    return found ?? { id: avatarId, source: ACTIVE_SOURCE };
 }
-function resolveSource(explicit, avatar, validSources) {
-    const src = (explicit ?? '').trim() || (avatar.source ?? '').trim();
+function resolveSource(avatar, validSources) {
+    const src = (avatar.source ?? '').trim() || ACTIVE_SOURCE;
     if (!validSources.includes(src)) {
-        throw new SkillError(`❌ Could not determine a valid source (${validSources.join('/')}). Pass --source, or confirm the avatar carries a source field.`);
+        throw new SkillError(`❌ avatar uses provider "${src}", which is not available (supported: ${validSources.join('/')}). Pick another avatar from --list-avatars.`);
     }
     return src;
 }
+// ── Avatar cloning (HiFly) ─────────────────────────────────────────────────
+async function cloneAvatar(ctx, input) {
+    const fileUrl = toId(input.clone_url);
+    if (!/^https?:\/\//i.test(fileUrl)) {
+        throw new SkillError('❌ --clone needs --clone-url <public http(s) URL of a video or portrait image> (local files are not uploaded)');
+    }
+    const name = toId(input.name);
+    if (!name)
+        throw new SkillError('❌ --clone needs --name <avatar name>');
+    const sourceType = toId(input.clone_type) || 'video';
+    if (!CLONE_TYPES.includes(sourceType)) {
+        throw new SkillError(`❌ --clone-type must be one of ${CLONE_TYPES.join(' / ')}, received: ${sourceType}`);
+    }
+    const payload = { name, sourceType, fileUrl };
+    if (input.thumbnail_url)
+        payload.thumbnailUrl = toId(input.thumbnail_url);
+    if (input.gender)
+        payload.gender = toId(input.gender);
+    emitProgress({ phase: 'gen-digital-human:clone-request', sourceType });
+    const data = await mmPost(ctx, '/digital-human/avatar/clone', payload, { timeoutMs: 60_000 });
+    const avatarId = toId(data.id);
+    if (!avatarId) {
+        throw new SkillError(`❌ could not parse the new avatar id; API returned: ${JSON.stringify(data)}`);
+    }
+    emitProgress({ phase: 'gen-digital-human:clone-async', avatarId });
+    const json = isTrue(input.json_output);
+    if (input.wait !== undefined && !isTrue(input.wait)) {
+        if (json) {
+            process.stdout.write(JSON.stringify({ avatarId, cloneStatus: data.cloneStatus ?? 'cloning' }) + '\n');
+            return;
+        }
+        process.stdout.write(`\n🧬 Clone submitted, avatar id: ${avatarId}\n`);
+        process.stdout.write(`💡 Check progress with --clone-status --avatar-id ${avatarId}\n`);
+        return;
+    }
+    let final;
+    try {
+        final = await pollUntil(async () => {
+            const s = await mmPost(ctx, '/digital-human/avatar/clone-status', { id: avatarId }, { timeoutMs: 30_000 });
+            const status = s.cloneStatus ?? 'unknown';
+            emitProgress({ phase: 'gen-digital-human:clone-poll', avatarId, status });
+            if (status === 'done')
+                return s;
+            if (status === 'failed')
+                throw new SkillError(`❌ avatar clone failed: ${s.cloneError || 'unknown error'}`);
+            return null;
+        }, { intervalMs: 10_000, timeoutMs: 20 * 60_000 });
+    }
+    catch (err) {
+        if (err instanceof SkillError && /polling timed out/.test(err.message)) {
+            throw new SkillError(`❌ avatar ${avatarId} is still cloning; rerun --clone-status --avatar-id ${avatarId} later`);
+        }
+        throw err;
+    }
+    if (json) {
+        process.stdout.write(JSON.stringify({ avatarId, cloneStatus: final.cloneStatus }) + '\n');
+        return;
+    }
+    process.stdout.write(`\n✅ Avatar cloned, id: ${avatarId}\n`);
+    process.stdout.write(`💡 Generate with --avatar-id ${avatarId} --text "..."\n`);
+}
+async function checkCloneStatus(ctx, avatarId, json) {
+    const s = await mmPost(ctx, '/digital-human/avatar/clone-status', { id: avatarId }, { timeoutMs: 30_000 });
+    const status = s.cloneStatus || 'unknown';
+    if (json) {
+        process.stdout.write(JSON.stringify({ avatarId, cloneStatus: status, error: s.cloneError || null }) + '\n');
+        return;
+    }
+    process.stdout.write(`\nclone status: ${status}\n`);
+    if (status === 'failed')
+        process.stdout.write(`   failure reason: ${s.cloneError || 'unknown error'}\n`);
+}
+// ── Video generation ───────────────────────────────────────────────────────
 async function checkStatus(ctx, generationId, json) {
     const data = await mmPost(ctx, '/digital-human/video/status', { generationId }, { timeoutMs: 30_000 });
     const status = data.status ?? 'unknown';
@@ -93,25 +185,40 @@ export async function genDigitalHuman(input, ctxIn) {
         privateToken: input.priv_token,
         preflightToken: ctxIn.auth?.token,
     });
+    const json = isTrue(input.json_output);
     // ── Mode 1: list avatars ────────────────────────────────────────────────
     if (isTrue(input.list_avatars)) {
         return listAvatars(ctx, input);
     }
-    // ── Mode 3: check status ────────────────────────────────────────────────
+    // ── Mode 2: clone a custom avatar (HiFly) ───────────────────────────────
+    if (isTrue(input.clone)) {
+        return cloneAvatar(ctx, input);
+    }
+    // ── Mode 3: clone status ────────────────────────────────────────────────
+    if (isTrue(input.clone_status)) {
+        const avatarId = toId(input.avatar_id);
+        if (!avatarId)
+            throw new SkillError('❌ clone-status mode requires --avatar-id');
+        return checkCloneStatus(ctx, avatarId, json);
+    }
+    // ── Mode 4: check generation status ─────────────────────────────────────
     if (isTrue(input.check_status)) {
         const generationId = toNumber(input.generation_id, 'generation_id');
         if (generationId === undefined) {
             throw new SkillError('❌ check-status mode requires --generation-id');
         }
-        return checkStatus(ctx, generationId, isTrue(input.json_output));
+        return checkStatus(ctx, generationId, json);
     }
-    // ── Mode 2: generate (default) ──────────────────────────────────────────
-    const avatarId = toNumber(input.avatar_id, 'avatar_id');
-    if (avatarId === undefined) {
+    // ── Mode 5: generate (default) ──────────────────────────────────────────
+    const avatarId = toId(input.avatar_id);
+    if (!avatarId) {
         throw new SkillError('❌ provide --avatar-id to pick the avatar (use --list-avatars to see available avatars)');
     }
     const audioUrl = (input.audio_url ?? '').trim();
     const text = input.text ?? '';
+    if (audioUrl && !/^https?:\/\//i.test(audioUrl)) {
+        throw new SkillError(`❌ --audio-url needs a public http(s) URL (local files are not uploaded), received: ${audioUrl}`);
+    }
     if (!audioUrl) {
         if (!text.trim()) {
             throw new SkillError('❌ in TTS mode provide --text, or use --audio-url for audio-driven mode');
@@ -120,12 +227,16 @@ export async function genDigitalHuman(input, ctxIn) {
     const dh = (await getCapabilities(input.api_base_url)).digitalHuman;
     emitProgress({ phase: 'gen-digital-human:resolve-avatar', avatarId });
     const avatar = await fetchAvatarInfo(ctx, avatarId);
-    const source = resolveSource(input.source, avatar, dh.sources);
+    if (avatar.cloneStatus === 'cloning') {
+        throw new SkillError(`❌ avatar ${avatarId} is still cloning; check with --clone-status --avatar-id ${avatarId}`);
+    }
+    if (avatar.cloneStatus === 'failed') {
+        throw new SkillError(`❌ avatar ${avatarId} failed to clone (${avatar.cloneError || 'unknown error'}); clone it again`);
+    }
+    const source = resolveSource(avatar, dh.sources);
     const payload = { avatarId, source };
     if (audioUrl) {
         payload.audioUrl = audioUrl;
-        if (text.trim())
-            payload.text = text.trim();
     }
     else {
         payload.text = text;
@@ -133,11 +244,6 @@ export async function genDigitalHuman(input, ctxIn) {
         if (input.voice_name)
             payload.voiceName = String(input.voice_name);
     }
-    const aspectRatio = input.aspect_ratio ?? avatar.aspectRatio;
-    if (aspectRatio)
-        payload.aspectRatio = aspectRatio;
-    if (input.prompt)
-        payload.prompt = String(input.prompt);
     emitProgress({ phase: 'gen-digital-human:request', avatarId, source, mode: audioUrl ? 'audio' : 'tts' });
     const data = await mmPost(ctx, '/digital-human/video/generate', payload, { timeoutMs: 60_000 });
     const generationId = data.generationId;
@@ -149,7 +255,7 @@ export async function genDigitalHuman(input, ctxIn) {
     if (!videoUrl) {
         throw new SkillError(`❌ video generated but no URL was returned; rerun --check-status --generation-id ${generationId} later`);
     }
-    if (isTrue(input.json_output)) {
+    if (json) {
         process.stdout.write(JSON.stringify({ url: videoUrl, generationId }) + '\n');
         return;
     }

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.55",
-  "generatedAt": "2026-09-28T12:06:33.998Z",
+  "version": "0.9.57",
+  "generatedAt": "2026-09-29T07:05:55.130Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -169,12 +169,12 @@
       "tier": "atomic",
       "category": "asset",
       "title": "Digital-Human Talking-Head",
-      "summary": "Digital-human video: list available avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL.",
+      "summary": "Digital-human video (HiFly): list or clone avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL. Aspect ratio follows the avatar's cloned source and cannot be chosen.",
       "triggers": [
         "Digital human, talking-head video, AI presenter, virtual host",
         "Make a talking-head video out of this script / this audio file",
         "List or browse digital-human avatars",
-        "Use Jimeng or HiFly to drive an avatar"
+        "Clone / create a custom avatar from a video or photo"
       ],
       "entry": {
         "type": "http",
@@ -199,15 +199,7 @@
           },
           "name": {
             "type": "string",
-            "description": "With list_avatars=true: fuzzy-filter avatars by name"
-          },
-          "source": {
-            "type": "string",
-            "enum": [
-              "jimeng",
-              "hifly"
-            ],
-            "description": "Provider: jimeng is image-driven, hifly is video-driven. Usually inferred from the avatar; pass it explicitly when the avatar declares no source."
+            "description": "With list_avatars=true: fuzzy-filter avatars by name. With clone=true: the new avatar's name (required)."
           },
           "gender": {
             "type": "string",
@@ -218,33 +210,53 @@
             "description": "Filter by gender"
           },
           "avatar_id": {
-            "type": "number",
-            "description": "Avatar id"
+            "type": "string",
+            "description": "Avatar id as returned by list_avatars (opaque string like dh_xxx). Also used with clone_status=true."
+          },
+          "clone": {
+            "type": "boolean",
+            "description": "Clone mode: create a custom HiFly avatar from a video (free) or a portrait image (costs HiFly credits). Requires clone_url and name. Waits until cloning finishes unless wait=false."
+          },
+          "clone_url": {
+            "type": "string",
+            "description": "With clone=true: public http(s) URL of the source. Video: mp4/mov (h264), 5s-30min, 360p-4K, ≤500MB, one clearly visible speaking person. Image: a front-facing portrait."
+          },
+          "clone_type": {
+            "type": "string",
+            "enum": [
+              "video",
+              "image"
+            ],
+            "description": "With clone=true: source type. Defaults to video."
+          },
+          "thumbnail_url": {
+            "type": "string",
+            "description": "With clone=true: optional cover image URL shown in avatar lists (image clones default to the image itself). The output aspect ratio always follows the cloned source; it cannot be chosen at generation time."
+          },
+          "wait": {
+            "type": "boolean",
+            "description": "With clone=true: set false to return right after submission (then poll with clone_status=true). Defaults to waiting up to ~20 minutes."
+          },
+          "clone_status": {
+            "type": "boolean",
+            "description": "Clone-status mode: report cloning / done / failed for avatar_id."
           },
           "text": {
             "type": "string",
-            "description": "Narration text (TTS mode)"
+            "description": "Narration text (TTS mode, ≤ 10000 chars). Synthesized with voice_id, then drives the avatar; the speech must last at least 5 s. Ignored when audio_url is given."
           },
           "audio_url": {
             "type": "string",
-            "description": "Audio URL (audio-driven mode)"
+            "description": "Audio-driven mode: public http(s) URL of mp3 / m4a / wav, 5 s – 30 min, ≤ 100 MB. Takes precedence over text / voice_id."
           },
           "voice_id": {
             "type": "string",
-            "description": "Voice id (TTS mode). Shares the Minimax catalog with gen-voice — call gen_voice with list_voices=true to see available ids rather than inventing one."
+            "description": "Voice id (TTS mode). Shares the catalog with gen-voice (including cloned voices) — call gen_voice with list_voices=true to see available ids rather than inventing one."
           },
           "voice_name": {
             "type": "string",
             "description": "Voice display name, recorded alongside voice_id for bookkeeping. Does not affect synthesis."
           },
-          "aspect_ratio": {
-            "type": "string",
-            "description": "Aspect ratio: 9:16 / 16:9 / 3:4 / 1:1. Defaults to the avatar's own ratio."
-          },
-          "prompt": {
-            "type": "string",
-            "description": "Action prompt describing how the avatar should perform, e.g. 'more hand gestures'"
-          },
           "check_status": {
             "type": "boolean",
             "description": "Status-check mode: poll an earlier job instead of starting a new one. Requires generation_id. Use this when a generate call timed out."
@@ -255,7 +267,7 @@
           },
           "json_output": {
             "type": "boolean",
-            "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output"
+            "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }; clone / clone-status: { avatarId, cloneStatus }) instead of human-readable output"
           }
         },
         "required": []
@@ -263,18 +275,20 @@
       "ui": {
         "primary": [
           "avatar_id",
-          "text"
-        ],
-        "advanced": [
-          "source",
+          "text",
           "voice_id",
-          "aspect_ratio",
-          "prompt",
           "audio_url"
         ],
+        "advanced": [],
         "hidden": [
           "json_output",
           "list_avatars",
+          "clone",
+          "clone_url",
+          "clone_type",
+          "thumbnail_url",
+          "wait",
+          "clone_status",
           "mine",
           "name",
           "gender",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.55",
+  "version": "0.9.57",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

package/skills/gen-digital-human/SKILL.md

@@ -1,111 +1,78 @@
 ---
 name: gen-digital-human
 description: |
-  Digital-human (talking-head) skill: list available avatars, run TTS-based or audio-driven lip-sync, and check the status of pending jobs. Backed by ab-api's digital-human endpoints (Jimeng / HiFly providers).
+  Digital-human (talking-head) skill backed by HiFly: list avatars, clone a custom avatar from a video or photo, drive an avatar with text (TTS) or an existing audio URL, and check the status of pending jobs.
 
   Use this skill immediately whenever the user asks for any of:
   - Digital human, talking-head video, AI presenter, virtual host
   - "Make a talking-head video out of this script / this audio file"
   - List or browse digital-human avatars
-  - Use Jimeng or HiFly to drive an avatar
+  - Clone / create a custom avatar from a video or photo
 
   Even without an explicit "use AI", any request that turns text or audio into a synthesized presenter video should route here.
 triggers:
   - Digital human, talking-head video, AI presenter, virtual host
   - "Make a talking-head video out of this script / this audio file"
   - List or browse digital-human avatars
-  - Use Jimeng or HiFly to drive an avatar
+  - Clone / create a custom avatar from a video or photo
 ---
 
 # Digital-Human Skill
 
-Wraps ab-api's digital-human endpoints (the same ones the web studio uses), authenticated with the **Tianyan privateToken**. Two providers: **Jimeng** (image-driven) and **HiFly** (video-driven). Generation is async — the handler submits the task and polls `/digital-human/video/status` until completion.
-
-> This skill was migrated from a Python script to an remixmate CLI HTTP handler (`entry.type: http`). The agent invocation is unchanged (same tool name `gen_digital_human`, same params as in `skill.json`); local repro goes through `remixmate gen-digital-human ...`.
+Wraps ab-api's digital-human endpoints (the same ones the web studio uses), authenticated with the **Tianyan privateToken**. The provider is **HiFly**: avatars are cloned from a video or photo, then driven by audio. Generation is async — the handler submits the task and polls `/digital-human/video/status` until completion.
 
 ## Capabilities
 
 | Capability | Description | API |
 |------------|-------------|-----|
-| List avatars | Page through available avatars; filter by source / gender / name | `POST /digital-human/avatar/page` |
-| TTS lip-sync | avatar + text + voice → talking-head video | `POST /digital-human/video/generate` |
+| List avatars | Public avatars, or your own with `--mine` | `POST /digital-human/avatar/page` |
+| Text-driven | avatar + text + voice → speech is synthesized, then drives the avatar | `POST /digital-human/video/generate` |
 | Audio-driven | avatar + existing audio URL → talking-head video | `POST /digital-human/video/generate` |
-| Check status | Poll the progress of a generation job | `POST /digital-human/video/status` |
+| Check status | Poll a generation job | `POST /digital-human/video/status` |
+| Clone avatar | Custom avatar from a video (free) or portrait photo (costs HiFly credits) | `POST /digital-human/avatar/clone` |
+| Clone status | `cloning` / `done` / `failed` for a cloned avatar | `POST /digital-human/avatar/clone-status` |
 
-**Cross-skill dependency**: voice ids are shared with `gen-voice` (same Minimax catalog). Use `gen-voice --list-voices` to see available voices.
+Avatar ids are opaque strings (e.g. `dh_xxx`) — always copy them from `--list-avatars`, never invent them.
 
-## Auth & environment
+**What you cannot choose**: aspect ratio and on-camera actions. The output keeps the framing of the source the avatar was cloned from (a 9:16 clone produces 9:16 videos). To get another ratio, clone the avatar from footage in that ratio.
 
-No skill-local env file — the executing process inherits the system environment.
+**Cross-skill dependency**: voice ids are shared with `gen-voice` (including cloned voices). Use `gen-voice --list-voices` to see them.
 
-- **Enterprise OpenClaw**: auth is already injected, **no need** for `PRIV_TOKEN` / `--priv-token`.
-- **Other environments**: configure the token. Without a token, non-interactive runs fail.
+## Auth & environment
 
 | Env var | Description | Default |
 |---------|-------------|---------|
-| `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
+| `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides (not needed in Enterprise OpenClaw) | none |
 | `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.ai/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
 ## Operations
 
-By default only the URL is printed; generation is async and the handler polls until done (typically 1–5 minutes), emitting `__progress__` lines. The resulting video URL is cloud-persisted — show it directly, no download needed.
+Generation typically takes 1–5 minutes; the handler polls and emits `__progress__` lines. The resulting video URL is cloud-persisted — show it directly, no download needed.
 
 ### 1. List avatars
 
 ```bash
-remixmate gen-digital-human --list-avatars
+remixmate gen-digital-human --list-avatars --name "教师"   # public avatars (~1000; always narrow with --name)
+remixmate gen-digital-human --list-avatars --mine     # your cloned avatars
+remixmate gen-digital-human --list-avatars --gender female --name "alice"
 ```
 
-Optional filters:
-
-```bash
-# Filter by source (jimeng = image-driven, hifly = video-driven)
-remixmate gen-digital-human --list-avatars --source jimeng
-remixmate gen-digital-human --list-avatars --source hifly
-
-# Filter by gender
-remixmate gen-digital-human --list-avatars --gender female
+### 2. Generate a video
 
-# Show your custom avatars
-remixmate gen-digital-human --list-avatars --mine
-
-# Filter by name
-remixmate gen-digital-human --list-avatars --name "alice"
-```
-
-> Custom avatars require `--mine`. When generating a video the handler auto-falls back from the public list to `mine: true` if needed.
-
-### 2. Generate a digital-human video
-
-#### TTS mode
+Pick exactly one driver: **text** (+ voice) or **audio**. With `--audio-url`, text and voice are ignored.
 
 ```bash
-remixmate gen-digital-human \
-  --avatar-id 7 \
-  --text "Hi everyone, welcome to the live stream — today I'll introduce a new product." \
+# Text-driven
+remixmate gen-digital-human --avatar-id dh_xxx \
+  --text "Hi everyone, today I'll introduce a new product." \
   --voice-id "male-qn-qingse"
-```
 
-#### TTS + custom voice + aspect ratio
-
-```bash
-remixmate gen-digital-human \
-  --avatar-id 7 \
-  --text "Hi class, here's our brand-new course." \
-  --voice-id "female-shaonv" \
-  --aspect-ratio "9:16"
+# Audio-driven
+remixmate gen-digital-human --avatar-id dh_xxx --audio-url "https://example.com/voice.mp3"
 ```
 
-#### Audio-driven mode
-
-```bash
-remixmate gen-digital-human \
-  --avatar-id 39 \
-  --source hifly \
-  --audio-url "https://example.com/voice.mp3" \
-  --aspect-ratio "16:9"
-```
+Limits: speech/audio must last **5 s – 30 min**; audio is mp3 / m4a / wav, ≤ 100 MB, public http(s) URL; text ≤ 10000 characters.
 
 ### 3. Check job status
 
@@ -113,67 +80,42 @@ remixmate gen-digital-human \
 remixmate gen-digital-human --check-status --generation-id 123
 ```
 
-## Common CLI flags
-
-### List avatars
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--list-avatars` | List avatars and exit | — |
-| `--source` | Filter by source: `jimeng` / `hifly` | no filter |
-| `--gender` | Filter by gender: `male` / `female` | no filter |
-| `--mine` | Limit to user's custom avatars | off |
-| `--name` | Fuzzy filter by name | no filter |
-
-### Generate video
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--avatar-id` | Avatar id (required) | — |
-| `-t` / `--text` | Speech text (required for TTS mode; optional with `--audio-url`) | — |
-| `--audio-url` | Audio URL (audio-driven mode) | none |
-| `--voice-id` | Voice id (TTS mode) | `male-qn-qingse` |
-| `--voice-name` | Voice display name (recordkeeping) | none |
-| `--source` | `jimeng` / `hifly` (inferable from avatar) | auto |
-| `--aspect-ratio` | `9:16` / `16:9` / `3:4` / `1:1` | avatar's default |
-| `--prompt` | Action prompt (e.g. "more hand gestures") | none |
-| `--api-base-url` | Override API root | see env vars |
-| `--priv-token` | Override token | see env vars |
-
-### Check status
+### 4. Clone a custom avatar
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--check-status` | Enter status-check mode | — |
-| `--generation-id` | Job id (required) | — |
+The source must be a public http(s) URL (local files are not uploaded). Video: mp4/mov (h264), 5 s – 30 min, 360p – 4K, ≤ 500 MB, one person speaking to camera. Cloning takes minutes; the handler waits (up to ~20 min) and prints the new avatar id. The avatar also shows up under 素材库 → 数字人 in the web app.
 
-## Typical flows
-
-### Flow A — TTS
-
-```
-1. List avatars → --list-avatars [--gender female]
-2. Pick avatar-id
-3. Confirm or polish the speech text
-4. (Optional) pick a voice → use gen-voice --list-voices
-5. Generate → --avatar-id <id> --text "..." --voice-id "female-shaonv"
-6. Show URL
-```
+```bash
+# Video clone (free)
+remixmate gen-digital-human --clone --name "My presenter" --clone-url "https://example.com/me.mp4"
 
-### Flow B — Audio-driven
+# Portrait photo clone (costs HiFly credits)
+remixmate gen-digital-human --clone --clone-type image --name "My presenter" --clone-url "https://example.com/me.jpg"
 
+# Submit without waiting, then poll
+remixmate gen-digital-human --clone --wait false --name "My presenter" --clone-url "https://example.com/me.mp4"
+remixmate gen-digital-human --clone-status --avatar-id dh_xxx
 ```
-1. List avatars → --list-avatars [--mine]
-2. Prepare an audio URL (gen-voice can produce one)
-3. Generate → --avatar-id <id> --audio-url "https://..." [--source hifly]
-4. Show URL
-```
-
-## Text guidance (TTS)
 
-- Punctuation drives pacing — commas short, periods long.
-- Keep individual jobs under ~500 characters.
-- Tone and style of the script affect the perceived voice.
+## Flags
+
+| Flag | Mode | Description | Default |
+|------|------|-------------|---------|
+| `--list-avatars` | list | List avatars and exit | — |
+| `--mine` | list | Only your own avatars | off |
+| `--gender` | list / clone | `male` / `female` | none |
+| `--name` | list / clone | Fuzzy filter; with `--clone` the new avatar's name (required) | — |
+| `--avatar-id` | generate / clone-status | Avatar id (required) | — |
+| `-t` / `--text` | generate | Script (text-driven) | — |
+| `--voice-id` | generate | Voice id (text-driven) | `male-qn-qingse` |
+| `--voice-name` | generate | Voice display name (recordkeeping only) | none |
+| `--audio-url` | generate | Audio URL (audio-driven) | none |
+| `--check-status` / `--generation-id` | status | Poll a generation job | — |
+| `--clone` / `--clone-url` | clone | Clone mode and source URL (required) | — |
+| `--clone-type` | clone | `video` / `image` | `video` |
+| `--thumbnail-url` | clone | Cover shown in lists | image itself / none |
+| `--wait` | clone | `false` to return right after submission | wait |
+| `--clone-status` | clone-status | Report clone status of `--avatar-id` | — |
+| `--api-base-url` / `--priv-token` | all | Overrides | see env vars |
 
 ## Credits
 
@@ -192,9 +134,10 @@ generation cost, and the balance is the only warning before a run fails with
 - **401** / **token missing** (non-OpenClaw): set `PRIV_TOKEN`.
 - **Business `code != 0`**: read `msg` on stderr.
 - **429**: rate-limited; retry later.
-- **Generation timeout**: the handler caps polling at ~10 minutes; use `--check-status --generation-id <id>` later.
-- **Empty TTS text**: provide non-empty `--text` or use `--audio-url`.
+- **Generation timeout**: polling caps at ~10 minutes; use `--check-status --generation-id <id>` later.
+- **Speech/audio under 5 s**: lengthen the text or audio.
 - **Invalid voice id**: re-check via `gen-voice --list-voices`.
 - **Avatar id not found**: re-check via `--list-avatars` (or `--list-avatars --mine`).
-- **Cannot infer source**: when the avatar lacks a `source` and `--source` is not set, pass `--source jimeng` or `--source hifly` explicitly.
+- **Avatar still cloning / clone failed**: poll `--clone-status --avatar-id <id>`; on failure, re-clone with a clearer source (single speaker facing the camera, h264 mp4).
+- **User asks for a different aspect ratio or gestures**: not supported at generation time — explain that the ratio follows the cloned source, and offer to clone from footage in the wanted ratio.
 - **Network**: verify connectivity and `MM_API_BASE_URL`.

package/skills/gen-digital-human/skill.json

@@ -4,7 +4,7 @@
   "tier": "atomic",
   "category": "asset",
   "title": "Digital-Human Talking-Head",
-  "description": "Digital-human video: list available avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL.",
+  "description": "Digital-human video (HiFly): list or clone avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL. Aspect ratio follows the avatar's cloned source and cannot be chosen.",
   "auth": "required",
   "joinsTake": true,
   "envVars": [
@@ -29,15 +29,7 @@
       },
       "name": {
         "type": "string",
-        "description": "With list_avatars=true: fuzzy-filter avatars by name"
-      },
-      "source": {
-        "type": "string",
-        "enum": [
-          "jimeng",
-          "hifly"
-        ],
-        "description": "Provider: jimeng is image-driven, hifly is video-driven. Usually inferred from the avatar; pass it explicitly when the avatar declares no source."
+        "description": "With list_avatars=true: fuzzy-filter avatars by name. With clone=true: the new avatar's name (required)."
       },
       "gender": {
         "type": "string",
@@ -48,33 +40,53 @@
         "description": "Filter by gender"
       },
       "avatar_id": {
-        "type": "number",
-        "description": "Avatar id"
+        "type": "string",
+        "description": "Avatar id as returned by list_avatars (opaque string like dh_xxx). Also used with clone_status=true."
+      },
+      "clone": {
+        "type": "boolean",
+        "description": "Clone mode: create a custom HiFly avatar from a video (free) or a portrait image (costs HiFly credits). Requires clone_url and name. Waits until cloning finishes unless wait=false."
+      },
+      "clone_url": {
+        "type": "string",
+        "description": "With clone=true: public http(s) URL of the source. Video: mp4/mov (h264), 5s-30min, 360p-4K, ≤500MB, one clearly visible speaking person. Image: a front-facing portrait."
+      },
+      "clone_type": {
+        "type": "string",
+        "enum": [
+          "video",
+          "image"
+        ],
+        "description": "With clone=true: source type. Defaults to video."
+      },
+      "thumbnail_url": {
+        "type": "string",
+        "description": "With clone=true: optional cover image URL shown in avatar lists (image clones default to the image itself). The output aspect ratio always follows the cloned source; it cannot be chosen at generation time."
+      },
+      "wait": {
+        "type": "boolean",
+        "description": "With clone=true: set false to return right after submission (then poll with clone_status=true). Defaults to waiting up to ~20 minutes."
+      },
+      "clone_status": {
+        "type": "boolean",
+        "description": "Clone-status mode: report cloning / done / failed for avatar_id."
       },
       "text": {
         "type": "string",
-        "description": "Narration text (TTS mode)"
+        "description": "Narration text (TTS mode, ≤ 10000 chars). Synthesized with voice_id, then drives the avatar; the speech must last at least 5 s. Ignored when audio_url is given."
       },
       "audio_url": {
         "type": "string",
-        "description": "Audio URL (audio-driven mode)"
+        "description": "Audio-driven mode: public http(s) URL of mp3 / m4a / wav, 5 s – 30 min, ≤ 100 MB. Takes precedence over text / voice_id."
       },
       "voice_id": {
         "type": "string",
-        "description": "Voice id (TTS mode). Shares the Minimax catalog with gen-voice — call gen_voice with list_voices=true to see available ids rather than inventing one."
+        "description": "Voice id (TTS mode). Shares the catalog with gen-voice (including cloned voices) — call gen_voice with list_voices=true to see available ids rather than inventing one."
       },
       "voice_name": {
         "type": "string",
         "description": "Voice display name, recorded alongside voice_id for bookkeeping. Does not affect synthesis."
       },
-      "aspect_ratio": {
-        "type": "string",
-        "description": "Aspect ratio: 9:16 / 16:9 / 3:4 / 1:1. Defaults to the avatar's own ratio."
-      },
-      "prompt": {
-        "type": "string",
-        "description": "Action prompt describing how the avatar should perform, e.g. 'more hand gestures'"
-      },
       "check_status": {
         "type": "boolean",
         "description": "Status-check mode: poll an earlier job instead of starting a new one. Requires generation_id. Use this when a generate call timed out."
@@ -85,7 +97,7 @@
       },
       "json_output": {
         "type": "boolean",
-        "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output"
+        "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }; clone / clone-status: { avatarId, cloneStatus }) instead of human-readable output"
       }
     },
     "required": []
@@ -93,18 +105,20 @@
   "ui": {
     "primary": [
       "avatar_id",
-      "text"
-    ],
-    "advanced": [
-      "source",
+      "text",
       "voice_id",
-      "aspect_ratio",
-      "prompt",
       "audio_url"
     ],
+    "advanced": [],
     "hidden": [
       "json_output",
       "list_avatars",
+      "clone",
+      "clone_url",
+      "clone_type",
+      "thumbnail_url",
+      "wait",
+      "clone_status",
       "mine",
       "name",
       "gender",

package/skills/gen-digital-human/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-digital-human",
   "repoName": "agent-skill-media-maker",
   "skillId": "336",
-  "version": "V8",
-  "skillDescription": "Digital-human (talking-head) skill: list available avatars, run TTS-based or audio-driven lip-sync, and check the status of pending jobs. Backed by ab-api's digital-human endpoints (Jimeng / HiFly providers).\n\nUse this skill immediately whenever the user asks for any of:\n- Digital human, talking-head video, AI presenter, virtual host\n- \"Make a talking-head video out of this script / this audio file\"\n- List or browse digital-human avatars\n- Use Jimeng or HiFly to drive an avatar\n\nEven without an explicit \"use AI\", any request that turns text or audio into a synthesized presenter video should route here."
+  "version": "V9",
+  "skillDescription": "Digital-human (talking-head) skill backed by HiFly: list avatars, clone a custom avatar from a video or photo, drive an avatar with text (TTS) or an existing audio URL, and check the status of pending jobs.\n\nUse this skill immediately whenever the user asks for any of:\n- Digital human, talking-head video, AI presenter, virtual host\n- \"Make a talking-head video out of this script / this audio file\"\n- List or browse digital-human avatars\n- Clone / create a custom avatar from a video or photo\n\nEven without an explicit \"use AI\", any request that turns text or audio into a synthesized presenter video should route here."
 }