@remixmate/cli 0.9.16 → 0.9.18

package/dist/project/store.js

@@ -0,0 +1,97 @@
+/**
+ * Persistent project binding — which Project should this machine's CLI output
+ * belong to?
+ *
+ * Stored at ~/.config/remixmate/projects.json, NOT in credentials.json: that
+ * file is a 0600 secret store keyed by API base URL, with different lifetime
+ * and different blast radius on corruption.
+ *
+ * Two layers, because host cwd semantics are not uniform:
+ *   - `byPath`  — keyed by absolute cwd. Hosts that run inside the user's real
+ *                 repo (Codex, Claude Code) get per-repo bindings.
+ *   - `default` — a single fallback. Hosts that spawn a throwaway working
+ *                 directory per conversation (WorkBuddy uses
+ *                 ~/WorkBuddy/<timestamp>) would never hit a byPath entry, so a
+ *                 cwd-only design silently degrades to nothing for them.
+ *
+ * See docs/cli-project-binding-design.md §3.
+ */
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promises as fs } from 'node:fs';
+export const CONFIG_DIR = join(homedir(), '.config', 'remixmate');
+export const PROJECTS_FILE = join(CONFIG_DIR, 'projects.json');
+/**
+ * Must build a NEW object every call, not spread a shared constant: `backends`
+ * would then be one object aliased by every "empty" read, and writeBinding
+ * mutates it — so a later read of a missing/corrupt file would hand back
+ * bindings accumulated earlier in the process instead of nothing.
+ */
+function emptyFile() {
+    return { version: 1, backends: {} };
+}
+async function readFile() {
+    try {
+        const raw = await fs.readFile(PROJECTS_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.backends)
+            return emptyFile();
+        return parsed;
+    }
+    catch {
+        // Missing or corrupt → behave as unbound. A broken binding file must never
+        // block a render; the resolution ladder just falls through to the default project.
+        return emptyFile();
+    }
+}
+async function writeFile(data) {
+    await fs.mkdir(dirname(PROJECTS_FILE), { recursive: true, mode: 0o700 });
+    await fs.writeFile(PROJECTS_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+/** Look up the binding for a cwd: exact byPath match first, then the default. */
+export async function readBinding(apiBaseUrl, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl];
+    if (!entry)
+        return null;
+    const byPath = entry.byPath?.[resolve(cwd)];
+    if (byPath)
+        return { projectId: byPath, scope: 'path' };
+    if (entry.default)
+        return { projectId: entry.default, scope: 'default' };
+    return null;
+}
+/** Bind a project to this cwd (`scope: 'path'`) or as the fallback (`'default'`). */
+export async function writeBinding(apiBaseUrl, projectId, scope, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl] ?? {};
+    if (scope === 'default') {
+        entry.default = projectId;
+    }
+    else {
+        entry.byPath = { ...(entry.byPath ?? {}), [resolve(cwd)]: projectId };
+    }
+    file.backends[apiBaseUrl] = entry;
+    await writeFile(file);
+}
+/** Drop a binding. Returns true when something was actually removed. */
+export async function clearBinding(apiBaseUrl, scope, cwd = process.cwd()) {
+    const file = await readFile();
+    const entry = file.backends[apiBaseUrl];
+    if (!entry)
+        return false;
+    let removed = false;
+    if (scope === 'default') {
+        removed = entry.default != null;
+        delete entry.default;
+    }
+    else {
+        const key = resolve(cwd);
+        removed = entry.byPath?.[key] != null;
+        if (entry.byPath)
+            delete entry.byPath[key];
+    }
+    if (removed)
+        await writeFile(file);
+    return removed;
+}

package/dist/project/take.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Take creation — turn a render invocation into a VideoProject the web app can
+ * show, and hand its conversation id down to the skill.
+ *
+ * Why this exists at all: ab-web derives a video's project from
+ * `file.conversation_id → media_video_project → media_project`. A render whose
+ * upload carries no conversation id is stored correctly but belongs to nothing,
+ * so it shows up only in the raw asset list. The cloud agent injects
+ * CONVERSATION_ID for its own runs; locally, nobody did — that is the bug this
+ * module fixes.
+ *
+ * Idempotency lives on the server (`/video-project/ensure` is get-or-create on
+ * `(user_id, client_session_key)`), not in a local state file: a pipeline is N
+ * separate CLI processes, sometimes concurrent, and a local cache would have to
+ * solve staleness and write races that a unique index solves for free.
+ *
+ * See docs/cli-project-binding-design.md §5.
+ */
+import { type HttpContext } from '../http.js';
+export interface EnsuredTake {
+    conversationId: string;
+    videoProjectId: string;
+    projectId: string;
+    created: boolean;
+    attempt: number;
+}
+/**
+ * Look up the take for the current grouping key without creating anything.
+ *
+ * Used by pipeline skills that should attach to a take when one exists but must
+ * never bring one into being: someone running `remixmate gen-image` on its own
+ * isn't making a video, and an empty VideoProject is worse clutter than an
+ * unattributed image.
+ *
+ * Deliberately does NOT resolve a project — resolveProject()'s last rung
+ * lazily *creates* 「未分类」, which a read-only lookup has no business doing.
+ */
+export declare function findTake(ctx: HttpContext): Promise<EnsuredTake | null>;
+/**
+ * Resolve project + grouping key, then get-or-create the take.
+ * Returns null when this invocation shouldn't own a take.
+ */
+export declare function ensureTake(ctx: HttpContext, opts: {
+    jobId?: number;
+    flagProjectId?: string;
+}): Promise<EnsuredTake | null>;

package/dist/project/take.js

@@ -0,0 +1,102 @@
+/**
+ * Take creation — turn a render invocation into a VideoProject the web app can
+ * show, and hand its conversation id down to the skill.
+ *
+ * Why this exists at all: ab-web derives a video's project from
+ * `file.conversation_id → media_video_project → media_project`. A render whose
+ * upload carries no conversation id is stored correctly but belongs to nothing,
+ * so it shows up only in the raw asset list. The cloud agent injects
+ * CONVERSATION_ID for its own runs; locally, nobody did — that is the bug this
+ * module fixes.
+ *
+ * Idempotency lives on the server (`/video-project/ensure` is get-or-create on
+ * `(user_id, client_session_key)`), not in a local state file: a pipeline is N
+ * separate CLI processes, sometimes concurrent, and a local cache would have to
+ * solve staleness and write races that a unique index solves for free.
+ *
+ * See docs/cli-project-binding-design.md §5.
+ */
+import { mmPost } from '../http.js';
+import { resolveTakeKey } from './host.js';
+import { resolveProject } from './resolve.js';
+/**
+ * Pull title / aspectRatio / templateId off the persisted render job.
+ *
+ * The VideoProject row needs them at creation time, but this runs in Node
+ * before the Python renderer is spawned, so the DSL itself isn't in reach —
+ * `render_jobs.dsl_meta` is the summary of exactly those fields. Best-effort:
+ * a take with a placeholder title beats no take at all.
+ */
+async function fetchJobMeta(ctx, jobId) {
+    try {
+        const detail = await mmPost(ctx, '/renderJob/get', { jobId });
+        return detail?.dslMeta ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Look up the take for the current grouping key without creating anything.
+ *
+ * Used by pipeline skills that should attach to a take when one exists but must
+ * never bring one into being: someone running `remixmate gen-image` on its own
+ * isn't making a video, and an empty VideoProject is worse clutter than an
+ * unattributed image.
+ *
+ * Deliberately does NOT resolve a project — resolveProject()'s last rung
+ * lazily *creates* 「未分类」, which a read-only lookup has no business doing.
+ */
+export async function findTake(ctx) {
+    const takeKey = resolveTakeKey(undefined);
+    if (!takeKey.key)
+        return null;
+    const res = await mmPost(ctx, '/video-project/find-by-session', {
+        clientSessionKey: takeKey.key,
+    });
+    if (!res?.conversationId)
+        return null;
+    return {
+        conversationId: res.conversationId,
+        videoProjectId: res.id,
+        projectId: res.projectId ?? '',
+        created: false,
+        attempt: res.attempt ?? 0,
+    };
+}
+/**
+ * Resolve project + grouping key, then get-or-create the take.
+ * Returns null when this invocation shouldn't own a take.
+ */
+export async function ensureTake(ctx, opts) {
+    const jobId = opts.jobId && opts.jobId > 0 ? opts.jobId : undefined;
+    const takeKey = resolveTakeKey(jobId);
+    // No grouping key at all → don't create. Only reachable for a take-creating
+    // skill that has no jobId (prepare-video-assets) on a host that exposes no
+    // session id. Creating here would produce an ungrouped take that the later
+    // render-video call — which *does* have a jobId, hence the `job:N` key —
+    // could not join, leaving two takes for one video.
+    if (!takeKey.key)
+        return null;
+    const { projectId } = await resolveProject(ctx, { flagProjectId: opts.flagProjectId });
+    const meta = jobId ? await fetchJobMeta(ctx, jobId) : {};
+    const res = await mmPost(ctx, '/video-project/ensure', {
+        projectId,
+        clientSessionKey: takeKey.key,
+        clientHost: takeKey.host,
+        jobId: jobId ?? 0,
+        title: meta?.title ?? '',
+        archetype: meta?.archetype ?? '',
+        aspectRatio: meta?.aspectRatio ?? '',
+        templateId: meta?.templateId ?? '',
+    });
+    if (!res?.conversationId)
+        return null;
+    return {
+        conversationId: res.conversationId,
+        videoProjectId: res.id,
+        projectId,
+        created: res.created,
+        attempt: res.attempt,
+    };
+}

package/dist/registry.d.ts

@@ -16,6 +16,12 @@ export interface SkillDef {
     entry: SkillEntry;
     /** Authorization requirement enforced by the dispatcher before invocation. */
     auth: SkillAuthMode;
+    /** Ensure a take (VideoProject + conversation) before running — see skill-schema.ts. */
+    createsTake: boolean;
+    /** Attach to an existing take, never create one — see skill-schema.ts. */
+    joinsTake: boolean;
+    /** Argv keys that downgrade createsTake to joinsTake — see skill-schema.ts. */
+    createsTakeUnless: string[];
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -38,6 +38,9 @@ function loadOne(skillDir) {
         parameters: raw.parameters ?? {},
         entry,
         auth: resolveAuthMode(raw),
+        createsTake: raw.createsTake === true,
+        joinsTake: raw.joinsTake === true,
+        createsTakeUnless: Array.isArray(raw.createsTakeUnless) ? raw.createsTakeUnless : [],
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.d.ts

@@ -9,6 +9,7 @@
  *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
+import { type SkillDef } from './registry.js';
 import type { ParsedArgs } from './argv.js';
 export interface RunOptions {
     /** Override the skills directory (defaults to the package's bundled skills/). */
@@ -19,3 +20,20 @@ export interface RunOptions {
     parsedArgs: ParsedArgs;
 }
 export declare function runSkill(skillName: string, opts: RunOptions): Promise<number>;
+/** What this invocation is allowed to do about attribution. */
+export type TakeMode = 'create' | 'join' | 'none';
+/**
+ * Decide the take mode from the skill's declaration *and* what this particular
+ * invocation was asked to do.
+ *
+ * The manifest flags alone are not enough, because they describe the skill, not
+ * the call: `render-video --help` prints usage and exits, and
+ * `render-video --resolve-only` stops after asset resolution. Both used to run
+ * the full createsTake path, so a help query was enough to mint an empty take
+ * and lazily create 「未分类」 — the exact clutter project/take.ts sets out to
+ * avoid ("an empty VideoProject is worse clutter than an unattributed image").
+ *
+ * Note that a downgraded run still *joins*: when its own pipeline already
+ * started a take under the same grouping key, assets it generates stay attached.
+ */
+export declare function resolveTakeMode(skill: Pick<SkillDef, 'createsTake' | 'joinsTake' | 'createsTakeUnless'>, args: ParsedArgs): TakeMode;

package/dist/runner.js

@@ -16,6 +16,8 @@ import { HANDLERS } from './handlers/index.js';
 import { EXIT, SkillError } from './errors.js';
 import { authChildEnv, ensureAuth } from './auth/ensure.js';
 import { emitBillingFooter } from './billing.js';
+import { resolveHttpContext } from './http.js';
+import { ensureTake, findTake } from './project/take.js';
 /** Read the token override accepted by both the TS handlers and the Python skills. */
 function tokenFlag(args) {
     const value = args.token ?? args.priv_token;
@@ -33,6 +35,7 @@ export async function runSkill(skillName, opts) {
             apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
             flagToken: tokenFlag(opts.parsedArgs),
         });
+        await applyTakeContext(skill, opts, auth);
         switch (skill.entry.type) {
             case 'python':
                 // Python children talk to ab-api themselves and print their own billing
@@ -58,6 +61,88 @@ export async function runSkill(skillName, opts) {
         emitBillingFooter();
     }
 }
+/**
+ * Decide the take mode from the skill's declaration *and* what this particular
+ * invocation was asked to do.
+ *
+ * The manifest flags alone are not enough, because they describe the skill, not
+ * the call: `render-video --help` prints usage and exits, and
+ * `render-video --resolve-only` stops after asset resolution. Both used to run
+ * the full createsTake path, so a help query was enough to mint an empty take
+ * and lazily create 「未分类」 — the exact clutter project/take.ts sets out to
+ * avoid ("an empty VideoProject is worse clutter than an unattributed image").
+ *
+ * Note that a downgraded run still *joins*: when its own pipeline already
+ * started a take under the same grouping key, assets it generates stay attached.
+ */
+export function resolveTakeMode(skill, args) {
+    // Introspection — the skill prints its usage and exits without producing
+    // anything, so it must not touch the backend at all.
+    if (args.help === true || args.h === true)
+        return 'none';
+    if (skill.createsTake) {
+        const downgraded = (skill.createsTakeUnless ?? []).some((key) => args[key] === true);
+        return downgraded ? 'join' : 'create';
+    }
+    return skill.joinsTake ? 'join' : 'none';
+}
+/**
+ * Attach this invocation to a take, publishing the result as `CONVERSATION_ID`.
+ * That variable is the only thing that makes an uploaded asset reachable from
+ * the web app — it rides the upload as `x-conversation-id` and lands in
+ * `file.conversation_id`.
+ *
+ * Writes `process.env` rather than returning a child-env patch, because the two
+ * dispatch paths consume it differently: spawned Python inherits the process
+ * environment, while http/builtin handlers run in-process and read it via
+ * resolveHttpContext(). Four of the seven take-joining skills are in-process
+ * handlers, so a child-env-only patch would silently do nothing for them.
+ * Safe here because the CLI runs exactly one skill per process.
+ *
+ * Two deliberate non-behaviours:
+ *   - An already-set CONVERSATION_ID is left alone. The cloud agent injects its
+ *     own, and so does our own parent when prepare-video-assets shells out to
+ *     gen-image / gen-voice. Re-deriving would fork the conversation.
+ *   - Any failure is downgraded to a warning. Attribution is a convenience;
+ *     losing it must never cost the user a render they already paid for. The
+ *     asset still uploads, just unattributed — exactly the old behaviour.
+ */
+async function applyTakeContext(skill, opts, auth) {
+    const mode = resolveTakeMode(skill, opts.parsedArgs);
+    if (mode === 'none')
+        return;
+    if ((process.env.CONVERSATION_ID ?? '').trim())
+        return;
+    if (!auth.token)
+        return;
+    try {
+        const ctx = await resolveHttpContext(skill.name, {
+            apiBaseUrl: auth.apiBaseUrl,
+            preflightToken: auth.token,
+        });
+        let take;
+        if (mode === 'create') {
+            const jobIdArg = opts.parsedArgs.job_id;
+            const jobId = typeof jobIdArg === 'number' ? jobIdArg : Number(jobIdArg);
+            const flagProject = opts.parsedArgs.project;
+            take = await ensureTake(ctx, {
+                jobId: Number.isFinite(jobId) ? jobId : undefined,
+                flagProjectId: typeof flagProject === 'string' ? flagProject : undefined,
+            });
+        }
+        else {
+            take = await findTake(ctx);
+        }
+        if (!take)
+            return;
+        process.env.CONVERSATION_ID = take.conversationId;
+        process.stdout.write(`📁 take ${take.created ? 'created' : 'reused'}: ${take.videoProjectId} ` +
+            `(project ${take.projectId}${take.attempt ? `, attempt ${take.attempt}` : ''})\n`);
+    }
+    catch (err) {
+        process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${err.message}\n`);
+    }
+}
 async function runPython(skill, rawArgs, auth) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);

package/dist/skill-schema.d.ts

@@ -58,6 +58,29 @@ export interface RawSkillJson {
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
+    /**
+     * Declares that this skill produces a finished video, so the dispatcher should
+     * ensure a "take" (VideoProject + conversation) before running it and inject the
+     * resulting CONVERSATION_ID. Declarative rather than a hardcoded skill name in
+     * runner.ts, so the pipeline's shape stays visible in the skill's own manifest.
+     */
+    createsTake?: boolean;
+    /**
+     * Declares that this skill contributes to a video but must never *start* one:
+     * attach to an existing take if there is one, otherwise carry on unattributed.
+     * A standalone `gen-image` run isn't a video, and an empty VideoProject is
+     * worse clutter than an unattributed asset.
+     */
+    joinsTake?: boolean;
+    /**
+     * Parsed-argv keys (snake_case, as produced by argv.ts) whose presence means
+     * *this* invocation won't finish a video — `render-video --resolve-only`
+     * resolves assets and stops. Such a run degrades from createsTake to
+     * joinsTake: it still attaches to a take its own pipeline already started,
+     * but never brings one — nor the lazily created 「未分类」 — into being for a
+     * pass that may end in a contract error and no video at all.
+     */
+    createsTakeUnless?: string[];
 }
 /**
  * Resolve a skill's auth mode, defaulting for records that predate the field.

package/dist/skill-schema.js

@@ -61,6 +61,37 @@ export function validateSkillJson(raw, skillId) {
     if (raw.auth != null && !AUTH_VALUES.includes(raw.auth)) {
         errors.push(`skill.json.auth must be one of ${AUTH_VALUES.join(' | ')}, got '${raw.auth}'`);
     }
+    if (raw.createsTake != null && typeof raw.createsTake !== 'boolean') {
+        errors.push(`skill.json.createsTake must be a boolean, got '${String(raw.createsTake)}'`);
+    }
+    if (raw.joinsTake != null && typeof raw.joinsTake !== 'boolean') {
+        errors.push(`skill.json.joinsTake must be a boolean, got '${String(raw.joinsTake)}'`);
+    }
+    if (raw.createsTakeUnless != null) {
+        if (!Array.isArray(raw.createsTakeUnless) ||
+            raw.createsTakeUnless.some((f) => typeof f !== 'string' || f === '')) {
+            errors.push("skill.json.createsTakeUnless must be an array of non-empty argv keys");
+        }
+        else if (raw.createsTake !== true) {
+            // It only ever downgrades createsTake; on any other skill it would read as
+            // working while doing nothing.
+            errors.push("skill.json.createsTakeUnless requires createsTake=true");
+        }
+        else if (raw.createsTakeUnless.some((f) => f.includes('-'))) {
+            // argv.ts hands the dispatcher snake_case keys, so `--resolve-only`
+            // arrives as `resolve_only`. A kebab entry would silently never match.
+            errors.push("skill.json.createsTakeUnless entries must be snake_case argv keys (e.g. 'resolve_only', not 'resolve-only')");
+        }
+    }
+    if (raw.createsTake === true && raw.joinsTake === true) {
+        errors.push("skill.json cannot set both 'createsTake' and 'joinsTake' — createsTake already implies joining");
+    }
+    // Attribution means calling ab-api as a specific user. An `auth: none` skill
+    // never touches the backend and produces no server-side file, so there is
+    // nothing to attribute — the flag would be dead config that reads as working.
+    if ((raw.createsTake === true || raw.joinsTake === true) && resolveAuthMode(raw) === 'none') {
+        errors.push("skill.json declares createsTake/joinsTake but auth='none' — a purely local skill has nothing to attribute");
+    }
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "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.json

@@ -6,26 +6,87 @@
   "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.",
   "auth": "required",
-  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
-  "entry": { "type": "http", "handler": "gen-digital-human" },
+  "joinsTake": true,
+  "envVars": [
+    "PRIV_TOKEN",
+    "MM_API_BASE_URL",
+    "AGENT_NAME"
+  ],
+  "entry": {
+    "type": "http",
+    "handler": "gen-digital-human"
+  },
   "parameters": {
     "type": "object",
     "properties": {
-      "list_avatars": { "type": "boolean", "description": "List available digital-human avatars" },
-      "mine": { "type": "boolean", "description": "With list_avatars=true: list the caller's own custom avatars instead of the public catalog. Custom avatars do not appear without this." },
-      "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." },
-      "gender": { "type": "string", "enum": ["male", "female"], "description": "Filter by gender" },
-      "avatar_id": { "type": "number", "description": "Avatar id" },
-      "text": { "type": "string", "description": "Narration text (TTS mode)" },
-      "audio_url": { "type": "string", "description": "Audio URL (audio-driven mode)" },
-      "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." },
-      "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." },
-      "generation_id": { "type": "number", "description": "Job id to poll (required when check_status=true)" },
-      "json_output": { "type": "boolean", "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output" }
+      "list_avatars": {
+        "type": "boolean",
+        "description": "List available digital-human avatars"
+      },
+      "mine": {
+        "type": "boolean",
+        "description": "With list_avatars=true: list the caller's own custom avatars instead of the public catalog. Custom avatars do not appear without this."
+      },
+      "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."
+      },
+      "gender": {
+        "type": "string",
+        "enum": [
+          "male",
+          "female"
+        ],
+        "description": "Filter by gender"
+      },
+      "avatar_id": {
+        "type": "number",
+        "description": "Avatar id"
+      },
+      "text": {
+        "type": "string",
+        "description": "Narration text (TTS mode)"
+      },
+      "audio_url": {
+        "type": "string",
+        "description": "Audio URL (audio-driven mode)"
+      },
+      "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."
+      },
+      "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."
+      },
+      "generation_id": {
+        "type": "number",
+        "description": "Job id to poll (required when check_status=true)"
+      },
+      "json_output": {
+        "type": "boolean",
+        "description": "Emit a JSON result (generate: { url, generationId }; list: { avatars }; check-status: { status, url }) instead of human-readable output"
+      }
     },
     "required": []
   }