ucloud-cli

CLI for UCloud Modelverse video generation. Architecture ported from MiniMax-AI/cli (mmxReferenceVersion: 1.0.15).

Install

From npm:

npm install -g ucloud-cli

For local development:

bun install
bun run build
npm link   # or: npm install -g .

Requires Bun for development and Node.js 18+ for the built binary.

Quick Start

Add your AstraFlow / Modelverse key to zsh:

echo 'export MODELVERSE_API_KEY="your-key"' >> ~/.zshrc
echo 'export MODELVERSE_REGION="global"' >> ~/.zshrc
source ~/.zshrc

Preview the generated request before spending on a video job:

ucloud video generate \
  --prompt "UGC coffee shop" \
  --enhance-mode llm \
  --dry-run \
  --output json \
  --show-cost

Submit a real video generation job:

ucloud auth login --api-key "$MODELVERSE_API_KEY"
ucloud video generate --prompt "Ocean waves at sunset" --download sunset.mp4

Commands

ucloud auth login --api-key <key>
ucloud auth status
ucloud video generate --prompt "A cat on the beach" --duration 5 --resolution 720p --download out.mp4
ucloud video generate --prompt "UGC coffee shop" --enhance-mode llm --download out.mp4
ucloud video generate --prompt "Ocean waves" --no-enhance-prompt --download out.mp4
ucloud video generate --prompt "A robot painting" --async --quiet
ucloud video task get --task-id <id> --output json
ucloud video download --task-id <id> --out video.mp4
ucloud config show
ucloud config set --key region --value global
ucloud config set --key endpoint --value https://api.umodelverse.ai

Video Models

| Alias | Model ID | Billing | Images | Notes | |-------|----------|---------|--------|-------| | seedance (default) | doubao-seedance-2-0-260128 | Output tokens | Yes | Prompt enhancement, optional audio, adaptive ratio | | happyhorse | happyhorse-1.0-t2v | Per-second | No | Native synced audio, text-only | | kling | kling-v3 | Per-second | Yes | --mode std\|pro, --sound on\|off, first/last frame |

Select with --model seedance|happyhorse|kling or a full model ID.

Image-to-Video

Seedance and Kling accept reference images. Local files are read and encoded automatically.

# Seedance reference image
ucloud video generate \
  --prompt "Animate the scene" \
  --image ref.png \
  --image-role reference_image \
  --dry-run --output json

# Seedance first + last frame
ucloud video generate \
  --prompt "Transition" \
  --image start.png --image-role first_frame \
  --image end.png --image-role last_frame \
  --dry-run --output json

# Kling first/last frame morph
ucloud video generate --model kling \
  --prompt "Morph between frames" \
  --image first.png --image-tail last.png \
  --mode pro --sound off \
  --dry-run --output json --show-cost

| Flag | Models | Description | |------|--------|-------------| | --image <path> | Seedance, Kling | Local file (repeatable) | | --image-url <url> | Seedance, Kling | Hosted URL (repeatable) | | --image-role <role> | Seedance | first_frame, last_frame, reference_image | | --image-tail <path> | Kling | Last-frame file (requires --image) | | --image-tail-url <url> | Kling | Last-frame URL |

Seedance embeds images in input.content[] as data:image/...;base64 and auto-adds @ImageN tags. Kling uses raw base64 in parameters.image / image_tail.

Cost Estimation

The API returns usage (tokens or duration) but not dollar amounts. Use --show-cost to print local estimates and actuals.

• Seedance — Estimates use heuristic tokens/s (~21,780/s at 720p); actual cost uses returned completion_tokens (total_tokens equals completion_tokens). Estimates are previews, not caps.
• Kling — Per-second rates from UCloud pricing matrix; duration × rate.
• HappyHorse — Per-second at 720p/1080p.

Dry-run with --output json --show-cost returns cost.estimate and cost.disclaimer. Completed jobs include cost.actual in JSON output.

Config: video_show_cost. Env: MODELVERSE_VIDEO_SHOW_COST.

Seedance Prompt Enhancement

For Seedance models, the CLI can rewrite prompts using the Seedance 2.0 Prompt Guide. Enhancement is on by default; synchronized audio is also on by default.

| Mode | Flag | Description | |------|------|-------------| | rules | (default) | Local, deterministic — reorders scene-first, appends camera/audio/constraints | | llm | --enhance-mode llm | DeepSeek V4 Flash rewrite via Modelverse chat API (reasoning ON) |

# Default: rules enhancement + audio ON
ucloud video generate --prompt "Ocean waves at sunset" --download out.mp4

# LLM enhancement (smarter for vague prompts)
ucloud video generate --prompt "UGC coffee shop, barista pouring latte art" \
  --duration 5 --enhance-mode llm --download out.mp4

# Disable enhancement or audio
ucloud video generate --prompt "..." --no-enhance-prompt --download out.mp4
ucloud video generate --prompt "..." --no-generate-audio --download out.mp4

# Preview enhanced prompt without API call
ucloud video generate --prompt "..." --enhance-mode llm --dry-run --output json --show-cost

The CLI prints Original vs Enhanced on stderr (text mode) or includes a prompt object in JSON output. See generate-example/ for a verified smoke test.

Config keys: video_prompt_enhance, video_prompt_enhance_mode, video_prompt_enhance_model, video_generate_audio. Env: MODELVERSE_VIDEO_PROMPT_ENHANCE, MODELVERSE_VIDEO_GENERATE_AUDIO, MODELVERSE_VIDEO_SHOW_COST.

Development

bun run dev -- video generate --help
bun test
bun run typecheck
bun run build

Documentation

• RFC-001: CLI Design
• Command reference
• Agent skill (repo-local)
• UCloud doubao-seedance API
• UCloud ModelVerse pricing

Manual Smoke Test

1. Set MODELVERSE_API_KEY from AstraFlow console.
2. ucloud auth login --api-key "$MODELVERSE_API_KEY"
3. ucloud video generate --prompt "A calm lake at dawn" --duration 4 --resolution 480p --download smoke.mp4
4. Verify smoke.mp4 plays.

License

MIT