ucloud-cli

name	ucloud-cli
description	Use when an agent needs to install, configure, test, explain, publish, or operate ucloud-cli for AstraFlow/UCloud ModelVerse video generation, especially safe prompt enhancement, dry-run JSON previews, cost checks, async task handling, image-to-video, and MP4 downloads.

ucloud-cli

Use this skill to operate ucloud-cli safely for AstraFlow / UCloud ModelVerse video generation.

Default Workflow

1. Confirm the CLI is available:

ucloud --version
ucloud video generate --help

Inside this repo, use the development command when global ucloud is not installed:

bun run dev -- video generate --help

2. Check auth without exposing secrets:

ucloud auth status

Do not print full API keys. Prefer environment variables for agent and CI use:

export MODELVERSE_API_KEY="your-key"
export MODELVERSE_REGION="global"

The global region maps to https://api.umodelverse.ai. A user can also persist the region:

ucloud config set --key region --value global

3. Always preview real prompts before spending on video generation:

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

Inspect the JSON before submission:

• prompt.original
• prompt.enhanced
• prompt.used
• request
• cost.estimate
• cost.disclaimer (dry-run only)

4. Submit only after the user accepts the prompt/request/cost:

ucloud video generate \
  --prompt "UGC coffee shop" \
  --enhance-mode llm \
  --download out.mp4

Use async mode for automation:

ucloud video generate \
  --prompt "UGC coffee shop" \
  --async \
  --quiet \
  --output json

Then poll or download:

ucloud video task get --task-id <id> --output json
ucloud video download --task-id <id> --out out.mp4

Video Models

Alias	Model ID	Billing	Audio	Images	Prompt enhance
seedance	doubao-seedance-2-0-260128	Token output (USD/M)	--generate-audio / --no-generate-audio (default on)	i2v via input.content[]	Yes (rules / llm)
happyhorse	happyhorse-1.0-t2v	Per-second (USD)	Native synced audio (default on)	Not supported	No
kling	kling-v3	Per-second (USD)	--sound on|off (defaults from --generate-audio)	i2v via parameters.image / image_tail	No

When to Use Which Model

• Seedance — Default choice. Best for Seedance prompt enhancement, flexible aspect ratios (adaptive), optional audio, and multi-image i2v with roles. Billed by output tokens; use --show-cost and dry-run to preview spend.
• HappyHorse — Text-only UGC-style clips with native synced audio. No image inputs. Per-second billing at 720p/1080p.
• Kling — First/last-frame morphing and i2v with --mode std|pro quality tiers. Per-second billing from UCloud price.md kling-v3-omni matrix. No prompt enhancement.

Prompt Enhancement Rules

• Prompt enhancement applies to Seedance models only.
• Default enhancement mode is rules; use --enhance-mode llm when the prompt is vague or creative.
• Use --no-enhance-prompt when the user needs the prompt passed verbatim.
• Synchronized audio defaults to on. Use --no-generate-audio only when the requested output must be silent or audio is unwanted.

Image-to-Video (Seedance + Kling)

Agent workflow (Cursor / Codex)

When the user provides a workspace image path, pass it directly to --image. The CLI reads the file, encodes it, and builds the API request — no manual base64 or upload step.

# Seedance: reference image from workspace
ucloud video generate \
  --prompt "Animate the product on the counter" \
  --image /absolute/path/to/ref.png \
  --image-role reference_image \
  --dry-run --output json --show-cost

# Seedance: first + last frame (two --image flags, roles required)
ucloud video generate \
  --prompt "Transition from start to end" \
  --image ./start.png --image-role first_frame \
  --image ./end.png --image-role last_frame \
  --dry-run --output json

# Kling: first frame + tail frame
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

Use --image-url / --image-tail-url when the reference is already hosted.

Encoding and request shape

Seedance — input.content[] with text plus image_url items. Local files become data:image/<format>;base64,.... Roles: first_frame, last_frame, reference_image. Two images require first_frame + last_frame. The CLI auto-prepends @Image1 … @ImageN tags when the prompt omits them.

Kling — Raw base64 (no data: prefix) in parameters.image / parameters.image_tail. First image comes from --image or --image-url; tail from --image-tail or --image-tail-url (requires a first image).

HappyHorse — Does not support image inputs.

Model-specific flags

Concern	Seedance	Kling	HappyHorse
Audio	--generate-audio / --no-generate-audio	--sound on|off	Native (use --no-generate-audio to opt out)
Resolution	480p, 720p, 1080p	720p, 1080p	720p, 1080p
Quality tier	—	--mode std|pro (default std)	—
Camera	--camera-fixed	—	—

Cost Guidance

The API returns usage (tokens or duration) but not dollar amounts. The CLI computes cost locally from src/pricing/catalog.ts.

Estimates are heuristics, not caps. Always treat cost.estimate as a preview; actual billing follows returned usage.

Seedance (token output)

• Estimate (confidence: estimated): duration × tokens/s + image bonus. Heuristic rates: 480p ~18,000/s, 720p ~21,780/s, 1080p ~30,000/s; +5,000 tokens per reference image. Tier: t2v/i2v at 46 CNY/M, v2v at 28 CNY/M (FX 7.15).
• Actual (confidence: published): completion_tokens × published rate. API note: total_tokens equals completion_tokens. Example: 108,900 tokens @ $6.44/M (t2v/i2v) ≈ $0.701316.
• Dry-run stderr prints a cost note; JSON includes cost.disclaimer.

Kling (per-second)

• Estimate and actual (confidence: published): duration × rate from UCloud price.md kling-v3-omni matrix. Keys: std|pro × t2v|i2v × silent|sound. Example CNY/s: std:t2v:silent 0.6, pro:i2v:silent 1.2.
• i2v sound pricing falls back to i2v silent rate when no sound tier exists.

HappyHorse (per-second)

• Estimate and actual (confidence: published): duration × rate — 720p $0.126/s, 1080p $0.224/s.

Flags and output

• --show-cost — Print estimate before submit and actual after completion.
• --no-show-cost — Suppress cost lines.
• Config video_show_cost / env MODELVERSE_VIDEO_SHOW_COST for default.
• Dry-run JSON: cost.estimate + cost.disclaimer. Completed JSON: cost.actual when --output json.

SDK

Programmatic access via src/sdk/. VideoGenerateRequest fields:

• Images: images[] (path, url, role), imageTail, imageTailUrl
• Kling: mode (std | pro), sound (on | off)
• Cost: showCost — includes estimate in async return and buildDryRun()
• Enhancement: enhancePrompt, enhanceMode, enhanceModel; generateAudio defaults to true

import { UCloud } from 'ucloud-cli/sdk';

const client = new UCloud({ apiKey: process.env.MODELVERSE_API_KEY });

// Preview request + cost without API spend
const preview = await client.video.buildDryRun({
  prompt: 'Animate the scene',
  images: [{ path: './ref.png', role: 'reference_image' }],
  showCost: true,
});

// Submit async
const { taskId } = await client.video.generate({
  prompt: 'Ocean waves',
  model: 'kling',
  images: [{ path: './first.png' }],
  imageTail: './last.png',
  mode: 'pro',
  sound: 'off',
  async: true,
  showCost: true,
});

ModelVerse Context

ModelVerse exposes OpenAI-compatible chat completions at /v1/chat/completions. ucloud-cli uses this for LLM prompt enhancement.

ModelVerse handles long-running video jobs with asynchronous task endpoints:

• POST /v1/tasks/submit
• GET /v1/tasks/status?task_id=<id>

Responses can include usage data. The CLI uses local pricing metadata to show estimated or actual cost where possible.

Troubleshooting

• Auth error: check MODELVERSE_API_KEY, ucloud auth status, or ucloud auth login --api-key <key>.
• Wrong endpoint: use MODELVERSE_REGION=global or ucloud config set --key region --value global.
• Invalid video params: check model-specific duration, resolution, and ratio.
• Timeout/network error: retry with a longer --timeout, check proxy/env, and prefer --async for long jobs.
• Non-JSON API response: check endpoint and auth style first.
• Image validation: Kling --image-tail requires --image; Seedance two-image jobs need first_frame + last_frame roles.

Safety Rules

• Never reveal full API keys in chat, logs, screenshots, commits, or docs.
• Do not run real generation without user approval when it may spend credits.
• Prefer --dry-run --output json --show-cost as the first command for any new user prompt.
• Store final generated videos under an explicit --download path.