Happy Dreamina

happy-dreamina

Generate images and videos through ByteDance's official dreamina CLI. This skill is a thin instruction layer — it does not wrap any SDK. Every action maps to a dreamina subcommand the user's shell already has.

When to invoke this skill

Use this skill whenever any of these hold:

• The user says 即梦, Jimeng, or Dreamina (any language).
• The user explicitly names the dreamina CLI or its subcommands.
• The user asks about their Jimeng task history, account credit, or login status.

If the user just says "generate an image" or "画张图" without naming Jimeng, prefer happy-image-gen / happy-video-gen instead and do NOT trigger this skill. The reason is that Jimeng uses browser login and is one specific provider — other skills let the user pick from many providers via EXTEND.md defaults.

Step 0: Preflight (BLOCKING — run both checks before anything else)

Run these in parallel:

1. command -v dreamina — is the binary installed? 2. dreamina user_credit — is the login alive? A healthy response is JSON containing credit info.

If dreamina is not installed

Tell the user the dreamina CLI is missing and offer to install it. The official installer is:

curl -fsSL https://jimeng.jianying.com/cli | bash

This is a shell install that writes to the user's machine — do not run it silently. Confirm, then run it, then re-check command -v dreamina. See references/install-and-login.md for platform notes (macOS, Linux x86_64/arm64). For any other platform (e.g. Windows) or when the installer changes, point the user at the official install page: https://jimeng.jianying.com/ai-tool/install.

If user_credit fails (exit non-zero, or JSON missing credit)

The user is not logged in, or the token expired. Ask them to run:

dreamina login

This opens the default browser for Jimeng authorization. Credentials land in ~/.dreamina_cli/credential.json automatically — the user never handles the file. If the browser does not open or the flow hangs, escalate to dreamina login --debug (see references/troubleshooting.md).

Do not proceed to generation until `dreamina user_credit` succeeds.

Step 1: Pick the right subcommand

Map the user's intent to exactly one subcommand:

Step 2: Fill in parameters from the user's intent

Use references/ratio-resolution-map.md to convert natural language ("竖屏 / 1080P / 高清 / 方图 / 横屏") to flags. Pay attention to what the user did not say — fill in safe defaults, do not ask the user to restate obvious things.

Image generation — text2image / image2image

• --prompt="..." — always double-quote so shell metacharacters (Chinese quotes, commas) do not break.
• --ratio — 1:1 / 16:9 / 9:16 / 3:4 / 4:3. Default 1:1.
• --resolution_type — 1k / 2k / 4k. Default 2k; use 1k for fast draft, 4k only when the user asks for ultra or print-ready.
• For image2image only: `--images <path>` (plural — accepts a reference bundle, multiple paths space-separated).
• Always include --poll=30.

Video generation — text2video / image2video

• --prompt="..." — same quoting rule.
• --duration — integer seconds. Default 5.
• --ratio — default 16:9 for landscape intent, 9:16 for vertical, 1:1 for square.
• --video_resolution — 480P / 720P / 1080P. Default 720P.
• For image2video only: `--image <path>` (singular — a single keyframe).
• Always include --poll=60 (videos take longer than images).

⚠ Easy to confuse: image2image uses --images (plural, reference bundle). image2video uses --image (singular, one keyframe). Mixing them up gives "unknown flag" errors.

Step 3: Submit and read the result

Run the command via Bash. On success the CLI prints JSON to stdout — the result URL(s) or local file path(s) if --download_dir was passed. Echo the path/URL back to the user.

Example — text to image:

dreamina text2image \
  --prompt="一只戴墨镜的橘猫,背光,电影感" \
  --ratio=1:1 \
  --resolution_type=2k \
  --poll=30

Example — image to video:

dreamina image2video \
  --image=./keyframe.png \
  --prompt="镜头缓缓推近,橘猫眼神闪动" \
  --duration=5 \
  --ratio=16:9 \
  --video_resolution=720P \
  --poll=60

If the user wants the result downloaded locally rather than a URL, add --download_dir=./out (create the directory first).

Step 4: Handle async timeout

If --poll times out, the CLI returns JSON with status querying and a submit_id. Tell the user you will retry, then:

dreamina query_result --submit_id=<submit_id> --download_dir=./out

If the job is still in progress, wait and retry. If it failed, pull the error message from the query_result response and relay it verbatim — do not guess.

Advanced: history and sessions

• dreamina list_task --gen_status=success — list completed jobs.
• dreamina list_task --submit_id=<id> — fetch one specific job.
• Sessions (v1.3.5+) let the user keep separate workspaces for different projects. Only touch them if the user explicitly asks to "switch session", "work in session X", or "list sessions". Otherwise the default session is fine.

References

Load these on demand — do not read all up front:

• `references/cli-commands.md` — full flag table for every dreamina subcommand.
• `references/install-and-login.md` — installer details, browser login, credential file location, version upgrade.
• `references/ratio-resolution-map.md` — user phrasing ↔ --ratio / --resolution_type / --video_resolution mapping.
• `references/troubleshooting.md` — login expired, queue timeout, submit_id recovery, account switching.

dreamina CLI — full command reference

⚙ Authoritative source: dreamina <cmd> --help and dreamina --version on the user's own machine. This doc is a snapshot as of v1.3.5 (2026-04-16); if a flag below conflicts with what the CLI's own --help prints, trust the CLI. The Version history section at the bottom is not auto-updated.

All subcommands print JSON to stdout on success. Non-zero exit = failure; the JSON usually contains an error or message field.

Use --poll=<seconds> on any generation command to block up to that many seconds waiting for the result. If the deadline passes the call returns a querying status + submit_id so you can recover with query_result.

---

Auth & health

dreamina login [--debug]

Opens the default browser and walks through ByteDance / Douyin OAuth. On machines with no browser the CLI prints instructions for manually importing a login token. Credentials land in ~/.dreamina_cli/credential.json.

• --debug prints the OAuth callback URL and extra diagnostics. Use this when the browser does not open or the flow hangs.

dreamina relogin

Wipes the existing login and starts a fresh login flow. Use this to switch between Jimeng accounts.

dreamina logout

Clears ~/.dreamina_cli/credential.json. Does not delete config.toml or tasks.db.

dreamina user_credit

Returns a JSON object with remaining credit. The canonical health check — if this works, generation will work.

dreamina --version

Prints the installed CLI version. Starting v1.3.1 the CLI also prints an update notice at startup when a newer release exists.

---

Image generation

dreamina text2image

dreamina image2image

--images is plural (supports reference bundles). image2video's flag is --image (singular). Do not confuse them.

---

Video generation

dreamina text2video

dreamina image2video

---

Async recovery & history

dreamina query_result

Returns status success / querying / failed. For querying the job is still in progress — wait and retry.

dreamina list_task

Reads from the local ~/.dreamina_cli/tasks.db — no network round-trip for recent entries.

---

Sessions (v1.3.5+)

Separate workspaces for organizing tasks per project / per conversation. Only touch sessions if the user explicitly asks for them.

• dreamina session list
• dreamina session create <name>
• dreamina session switch <name>
• dreamina session delete <name>
• Generation commands accept --session=<name> to execute inside a specific session.

---

Version history (as of v1.3.5, 2026-04-16)

Run dreamina --version to check. If older than v1.3.x, suggest re-running the installer (v1.3.1+ has auto-update detection built in).

Install & login — dreamina CLI

Official install page: https://jimeng.jianying.com/ai-tool/install — always the source of truth. Check it first if a command below stops working, or when looking for a Windows / fresh-platform install path this skill has not documented yet.

🔐 Never paste the contents of `~/.dreamina_cli/credential.json` into issues, Slack, screenshots, or anywhere public. It contains the OAuth token and is equivalent to the user's Jimeng login. If support asks for "the credential", always redact the token first.

Install

One-liner (works on macOS, Linux x86_64, Linux arm64 since v1.3.4):

curl -fsSL https://jimeng.jianying.com/cli | bash

The installer drops a dreamina binary on the user's $PATH. Confirm with:

dreamina --version
command -v dreamina

Upgrade

Starting v1.3.1 the CLI prints an update banner on every run when a newer release exists. To force an upgrade, re-run the install command — it overwrites the existing binary.

Platform notes

• macOS (Apple Silicon or Intel): no extra steps.
• Linux x86_64: no extra steps.
• Linux arm64: requires v1.3.4 or later.
• Windows: not officially supported. WSL2 works as Linux x86_64.

---

Login

Interactive (preferred)

dreamina login

Opens the user's default browser for ByteDance / Douyin OAuth. After authorization, the CLI writes credentials to:

~/.dreamina_cli/credential.json

The user never edits this file directly.

Headless / no browser

If no display is available, the CLI prints step-by-step instructions for pasting a login token obtained on another machine. Follow the prompts.

Debugging login

dreamina login --debug

Prints the full OAuth callback URL and timing data. Share the output with Jimeng support if the flow hangs or errors out.

---

Verifying login

The canonical health check:

dreamina user_credit

Healthy response = JSON containing remaining credit. Any other output (HTML error page, non-zero exit, "unauthorized") means the login is broken.

---

Switching accounts

dreamina relogin

Clears the existing credential and runs login again. Use this to move between Jimeng accounts without losing config.toml or the local task DB.

---

Logging out

dreamina logout

Removes ~/.dreamina_cli/credential.json. Does not touch:

• ~/.dreamina_cli/config.toml (environment config)
• ~/.dreamina_cli/tasks.db (local task history)
• ~/.dreamina_cli/logs/ (operational logs)

If the user wants a truly clean slate, they can delete the whole ~/.dreamina_cli/ directory after logout.

---

Local files reference

---

When the user's environment is unusual

• Check ~/.dreamina_cli/config.toml exists and is non-empty. If it is missing, the installer did not finish — re-run the curl install.
• If user_credit returns a clear auth error but config.toml is fine, the login expired. Run dreamina relogin.
• If user_credit times out / fails to reach any endpoint, it is a network issue (proxy, VPN, firewall). Check connectivity to jimeng.jianying.com.

Natural language → dreamina flag mapping

Use this table when the user describes an aspect ratio or quality in words rather than exact flags. Pick the best match; never ask the user to restate what they already said implicitly.

---

Aspect ratio (--ratio)

Jimeng supports exactly five ratios. Map natural language to these only.

If the user gives a numeric ratio Jimeng does not support, fall back to the nearest supported one and mention the substitution in the reply.

---

Image resolution (--resolution_type)

Default: 2k when the user does not specify. 4k can be slow and more prone to queueing — v1.3.3 fixed a stuck-queue bug for 4k, but still expect longer wait times.

---

Video resolution (--video_resolution)

Default: 720P. Higher resolutions take noticeably longer — use --poll=90 or --poll=120 if you bump to 1080P.

---

Duration (--duration)

Jimeng videos are parametrized in whole seconds. Accept integer values.

Default: 5 seconds. If the user names a value outside the CLI-supported range, let the CLI reject it — don't silently clamp.

---

Composite phrases (common shortcuts)

---

What to always include

Regardless of what the user said, always pass:

• --prompt="..." — the full prompt, double-quoted.
• --poll=30 for images, --poll=60 for videos (--poll=90 for 1080P).

Why --poll matters

If you skip --poll, the CLI returns right away with a querying status + submit_id instead of the finished asset. The user then has to either know to run dreamina query_result --submit_id=... themselves, or wait for you to do it — both add friction for no benefit, since the user just asked for the image/video. Including --poll lets the CLI block on the user's behalf and return the actual result in one call. The only case where skipping makes sense is deliberate fire-and-forget batch submission, which is rare in an interactive chat.

Troubleshooting — dreamina CLI

Common failures and how to resolve them. Match the symptom first, then follow the steps.

---

"Command not found: dreamina"

Cause: binary not installed or not on $PATH.

Fix:

curl -fsSL https://jimeng.jianying.com/cli | bash
# Then open a fresh shell or:
hash -r
command -v dreamina

If the installer completes but dreamina is still missing, check the installer's output — it usually mentions which directory the binary went into and whether that directory is on $PATH.

---

user_credit fails / login errors after a successful login

Symptoms: dreamina login completes, browser shows success, but dreamina user_credit returns unauthorized.

Checklist (run in order):

1. Confirm ~/.dreamina_cli/config.toml exists and is non-empty. If missing, re-run the installer. 2. Confirm ~/.dreamina_cli/credential.json exists. If missing, login did not finish — rerun. 3. If both exist, run dreamina user_credit again — the first call after login can race the credential write. 4. Still failing? Run dreamina relogin to clear the old credential and start over. 5. If relogin also fails, it is either a network issue (see below) or a Jimeng service outage.

---

Browser login hangs / callback never returns

Cause: default browser cannot reach the CLI's local callback URL, or firewall blocks the loopback.

Fix:

dreamina login --debug

Debug mode prints the callback URL so the user can paste it manually into a browser on another machine if needed. Share the debug output with Jimeng support if the flow still does not complete.

---

Generation command errors "无权限" / "unauthorized" / 401

Cause: login expired or account lacks permission for the requested model tier.

Fix:

1. dreamina user_credit — if this fails, relogin. 2. If user_credit succeeds but a specific generation fails, the user's plan may not include that model or resolution. Try --resolution_type=2k instead of 4k, or drop to text2image from an advanced variant. 3. Check ~/.dreamina_cli/logs/ for the raw API response.

---

Async job stuck — --poll times out repeatedly

Cause: Jimeng queue is long, especially for 4k images or 1080P videos.

Fix:

1. Note the submit_id from the last response. 2. Wait a minute, then fetch manually:

   dreamina query_result --submit_id=<submit_id> --download_dir=./out

3. If query_result keeps returning status querying for more than ~15 minutes, something is wrong — pass the submit_id to Jimeng support. 4. 4k queueing specifically was buggy before v1.3.3 — run dreamina --version and upgrade if older.

---

Ultra-HD images still stuck in queue after v1.3.3 fix

If the user is on v1.3.2 or earlier, upgrade:

curl -fsSL https://jimeng.jianying.com/cli | bash

v1.3.3 (2026-04-07) fixed the stuck-queue bug for ultra-HD images. Confirm the fix with dreamina --version.

---

Switching accounts

dreamina relogin

Clears the existing credential and runs fresh OAuth. config.toml and tasks.db are preserved — past task history remains visible to the new account via list_task, though the new account may not be able to re-download them.

---

Clearing all local state

dreamina logout
rm -rf ~/.dreamina_cli   # only if the user wants a true clean slate

Warn before deleting ~/.dreamina_cli/ — it also wipes tasks.db (local history) and config.toml.

---

CLI out of date

Symptom: commands mentioned in the user's request (e.g., dreamina session ... for multi-session support) exit with "unknown command".

Fix:

dreamina --version
# If older than v1.3.5, upgrade:
curl -fsSL https://jimeng.jianying.com/cli | bash

Starting v1.3.1 the CLI prints an update banner automatically — if the user keeps ignoring it, the banner will eventually stop matching what the skill expects.

---

Network / proxy issues

If all Jimeng-facing calls fail but other HTTP calls work, the user's corporate proxy or VPN likely blocks *.jianying.com / jimeng.jianying.com. Check:

curl -I https://jimeng.jianying.com

If this hangs or fails TLS, the user must get the network unblocked before the CLI will work.

---

Last resort

If none of the above helps, collect and share with Jimeng support:

• dreamina --version
• Last 200 lines of the newest file in ~/.dreamina_cli/logs/
• The full output of dreamina <failing-command> --debug (most subcommands accept --debug)

Do not paste credential.json contents — they contain login tokens.