@byteplus/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

package/skills/arkcli-gen/references/arkcli-gen.md

@@ -0,0 +1,230 @@
+# +gen
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to learn about authentication, global parameters, and security rules.
+
+Execution-layer documentation for image/video generation (`+gen` full parameters).**This is step 3 of the three-step workflow**. For the complete workflow (① `resources list` to check profile models → ② `models get` to check supported_params → ③ `+gen` to generate), see [`../SKILL.md`](../SKILL.md).
+
+> **⚠️ Video tasks are asynchronous by default**: submission immediately returns a `task_id` (`status: queued`). Use `arkcli gen get <task_id>` to poll; add `--wait` to block synchronously (**capped** — at most `--timeout`, default 10m). Image tasks return synchronously.
+
+## Commands
+
+`+gen` has no `--no-progress` flag; do not copy the `+chat` heartbeat option. Capture complete stdout and stderr separately without suppressing errors.
+
+### CLI options are not HTTP/SDK payloads
+
+When troubleshooting HTTP/SDK code, inspect the actual API path, exact model/Endpoint, redacted authentication context, request body, accessible media, and response/error/request ID. CLI `--input`, local `@file`, and role shorthand require conversion; client-side `--wait`, `--save-to`, and open options are not model payload fields. Image unions and video `content[]` cannot be copied interchangeably.
+
+A successful `+gen` proves only that CLI workflow succeeded; it may have normalized input, supplied defaults, or selected a different calling context. It does not prove the user's original HTTP/SDK request is correct. Explain the actual differences, retain unknowns, and do not create an extra paid task instead of inspecting the code. Preview is a local plan, not server validation; preserve `partial/unresolved` and require authorization for any real test.
+
+> **⚠️ `--model` must be in the complete `<name>-<primary_version>` form (such as `seedream-5-0-260128` or `dreamina-seedance-2-0-260128`) or an endpoint ID (`ep-xxx`). Passing only the family name will result in a 404 `InvalidEndpointOrModel.NotFound`.**
+>
+> The `primary_version` format is not fixed. It is often a 6-digit date, but it may also be an 8-digit date, include a qualified prefix, be a short number, or even be an empty string (in which case the full ID is the family name itself). About half of models are not 6-digit versions. For details, see link 0 in [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md).**Do not use your own regular expression to decide "whether it looks like a complete ID".**
+>
+> **Complete before calling (required):** If you are not sure whether `--model` is already in complete form, run this first:
+>
+> ```bash
+> VER=$(arkcli models get <name> --transform 'primary_version' | tr -d '"')
+> # The --transform output includes JSON double quotes, so you must strip them with tr -d. Otherwise, $VER will be "260128", causing an incorrect concatenation.
+> MODEL=${VER:+<name>-$VER}; MODEL=${MODEL:-<name>}   # Falls back to <name> when VER is an empty string.
+> arkcli +gen --model "$MODEL" "<prompt>"
+> ```
+>
+> If you have just run `models search/list`, you can directly reuse the returned `primary_version` parameter without calling `get` again.
+
+## Video input roles: first frame / first-last frames / multi-reference (required reading)
+
+Seedance 2.x and similar services validate `content[].role` strictly. Do not rely on "the first image is
+the first frame" to infer the mode. Choose one mode from the user's intent before writing roles:
+
+| User intent | Recommended form | Notes |
+|---|---|---|
+| Single first frame (I2V) | `--input first_frame:@start.jpg` | The image is the starting frame |
+| First + last frames | `--input first_frame:@start.jpg --input last_frame:@end.jpg` | Each image constrains one end |
+| Multi-reference (subject/clothing/scene/style) | `--input reference_image:@ref1.jpg --input reference_image:@ref2.jpg` | Every image is a reference; the first one is **not** a first frame |
+| Reference video (R2V / continuation) | `--input reference_video:@ref.mp4`, optionally plus `--input reference_image:@person.jpg` | The video must be explicitly `reference_video` |
+
+Hard rules:
+
+- When generating commands, prefer the SDK role names `first_frame:` / `last_frame:` / `reference_image:` /
+  `reference_video:` / `reference_audio:`. The `first:` / `last:` / `ref:` forms are CLI aliases; do not mix
+  both dialects in one command, and do not rely on positional inference.
+- In a request carrying video or audio, every asset needs an explicit role. A missing image role is rejected
+  with HTTP 400 (`role must be specified for image contents`); a missing video role is rejected with
+  `reference media mode requires video role to be reference_video`.
+- Seedance 2.0 rejects mixing first-frame/first-last-frame mode with multi-reference mode. Do not send both
+  `first_frame` and `reference_image` unless the exact model capability explicitly allows it.
+- If the user supplies multiple images without saying which are first/last frames, confirm the roles before
+  submitting. Do not assume the first image is a first frame.
+- "Use this image as a reference" means `reference_image:`. Use `first_frame:` only for "start from this image"
+  or "make this the first frame". Do not probe role semantics by submitting paid tasks; check the model
+  metadata first, and use a local `--dry-run` when command shape needs verification.
+
+```bash
+# 1) Text-to-image (T2I) — Seedream model
+arkcli +gen --model seedream-5-0-260128 "Minimalist business laptop, dark blue, white background"
+
+# 2) Image-to-image / image-edit (I2I) — use --input to mention a reference image
+arkcli +gen --model seedream-5-0-260128 \
+  --input @ref.jpg \
+  "Keep the composition and change the background to a beach at dusk"
+
+# Multiple reference images (pass --input multiple times)
+arkcli +gen --model seedream-5-0-260128 \
+  --input @style1.jpg --input @style2.jpg \
+  "Blend the styles of the two images, with a Shiba Inu as the subject"
+
+# Generate multiple candidates at once (image-count > 1 automatically enables sequential)
+arkcli +gen --model seedream-5-0-260128 --image-count 4 "Four style variants of a futuristic city skyline"
+
+# 3) Text-to-video (T2V)
+arkcli +gen --model dreamina-seedance-2-0-260128 "A Shiba Inu running under cherry blossom trees, slow motion"
+
+# 4) Image-to-video / first-frame-to-video (I2V) — prefer explicit first_frame
+arkcli +gen --model dreamina-seedance-2-0-260128 \
+  --input first_frame:@first.jpg \
+  "The camera slowly pulls back while the subject stays still"
+
+# First and last frames: explicit first_frame / last_frame
+arkcli +gen --model dreamina-seedance-2-0-260128 \
+  --input first_frame:@start.jpg --input last_frame:@end.jpg \
+  "Generate tween animation between these two frames"
+
+# 5) Reference video (R2V) — the video must be explicitly reference_video
+arkcli +gen --model dreamina-seedance-2-0-260128 \
+  --input reference_video:@reference.mp4 \
+  "Keep the motion path of the reference video and replace the main character with a robot"
+
+# 6) Reference audio — synchronize the video rhythm with the audio
+arkcli +gen --model dreamina-seedance-2-0-260128 \
+  --input reference_audio:@beat.mp3 \
+  "A montage of city night scenes that cuts to the beat"
+
+# Advanced flags — image tasks
+arkcli +gen --model seedream-5-0-260128 \
+  --guidance-scale 7.5 --optimize-prompt --output-format png \
+  "Product photography style"
+
+# Advanced flags — video tasks
+arkcli +gen --model dreamina-seedance-2-0-260128 \
+  --frames 96 --camera-fixed --return-last-frame --draft \
+  "Aerial shot of a city at night"
+
+# Output full JSON
+arkcli +gen --model dreamina-seedance-2-0-260128 --format json "Product advertising video"
+
+# Custom inference endpoint: a real call resolves the bound model metadata
+arkcli +gen --model ep-20260416234150-zsd4v "Minimalist business laptop"
+
+# Add an explicit modality only for missing/conflicting metadata
+arkcli +gen --model ep-20260416234150-zsd4v --modality video "A Shiba Inu is running"
+```
+
+## Parameter
+
+| Parameter | Required | Type |Description|
+|------|------|------|------|
+| `<prompt>` |Yes| positional | Generation prompt (positional parameter, placed at the end of the command) |
+| `--model` | No| string | **Complete versioned model ID** (such as `seedream-5-0-260128` or `dreamina-seedance-2-0-260128`) or inference endpoint ID (`ep-xxx`). Passing only the family name will directly result in a 404 `InvalidEndpointOrModel.NotFound`.**Can be omitted in 0.1.16+**: when omitted, it falls back to the active profile's `Resources.<modality>.Default` based on `--modality`. If it is not set, a hint is reported to guide you to run `arkcli profile set-default --modality <m> <id>`. |
+| `--modality` | See description | string | Generation modality: `image` or `video`. Real calls use `explicit value > ArkModels output_modalities > FoundationModel task types > unknown`. |
+| `--input` | No| string (repeatable) | Reference asset references, added to content[] in the order they appear. Local file `@<path>` / remote `https://...` `tos://...` are all supported. **Local files (image/video/audio) are uploaded to TOS and replaced with a presigned https URL** that the backend fetches at submit time; `tos://<bucket>/<key>` is signed in place. Prefer the SDK role names `first_frame:` `last_frame:` `reference_image:` `reference_video:` `reference_audio:`. The `first:` `last:` `ref:` `none:` forms are CLI aliases that resolve to wire roles (`ref:` resolves by asset kind). Only an input with **no prefix at all** leaves the role empty for the server to infer by position; a bare `@<path>` is only for single-image I2V when the model accepts positional inference, and cannot express multi-reference. A request carrying a video must give that video an explicit `reference_video`, and every image in the same request needs a role too — otherwise the whole request is rejected with HTTP 400. Whether first-frame and multi-reference modes may be mixed depends on the exact model's `supported_params` / `description`; Seedance 2.0 rejects the mix.**Image tasks**: folded into an image union. **Video tasks**: assign roles explicitly according to the user's intent. |
+| `--inline-local` | No| bool | Embed local `--input` files as base64 data URLs instead of uploading them to TOS. **Images only**: an inlined image reference works, but an inlined video/audio reference is **rejected outright** by the data plane (HTTP 400, `reference_video must be provided as a web url`, no task created). Use when object storage is unavailable or you deliberately want no upload; do not use it as the default. |
+| `--name` | No| string | Task name override |
+| `--version` | No| string | Model version override |
+| `--size` | No| string | Image output size, such as `1920x1920`. The backend rejects it if the pixel count is too small. |
+| `--image-count` | No| int | Number of images output by an image task. When `>1`, it is automatically converted to `sequential_image_generation=auto + max_images=N`. |
+| `--n` | No| int | Alias of `--image-count` (image tasks). If both are passed, `--n` takes priority. |
+| `--ratio` | No| string | Output aspect ratio override, such as `16:9` / `9:16` / `1:1` (video tasks). |
+| `--resolution` | No| string | Output resolution, such as `480p`, `720p`, or `1080p` (video tasks). |
+| `--duration` | No| int | Video duration (seconds) |
+| `--frames` | No| int | Number of video frames (overrides duration on supported models). |
+| `--seed` | No| int | Random seed. The same seed can reproduce results. |
+| `--watermark` | No| bool | Whether to add a watermark. |
+| `--generate-audio` | No| bool | Whether to generate audio synchronously (video tasks). |
+| `--guidance-scale` | No| float | Classifier-free guidance scale for image tasks, such as `7.5`. |
+| `--optimize-prompt` | No| bool | Image tasks: enable server-side prompt optimization. |
+| `--output-format` | No| string | Image output format: `jpeg` or `png`. |
+| `--response-format` | No| string | Image response format: `url` (default) or `b64_json` (directly returns the image as a Base64 string and does not store a URL). |
+| `--prompt-thinking` | No| string | Image tasks: prompt optimization thinking mode `auto` / `enabled` / `disabled` (takes effect only when `--optimize-prompt=true`). |
+| `--prompt-mode` | No| string | Image tasks: prompt optimization execution mode `standard` / `fast`. |
+| `--sequential` | No| string | Image tasks: sequential image mode `auto` / `disabled`. When left empty, it keeps the automatic behavior of `--image-count > 1` → `auto`. Passing `disabled` explicitly forces single-image generation, even if `--image-count > 1`. |
+| `--stream` | No| bool | Image tasks: streaming NDJSON output. For details, see [`image-stream.md`](image-stream.md). |
+| `--camera-fixed` | No| bool | Video tasks: fix the virtual camera. |
+| `--return-last-frame` | No| bool | Video tasks: return the last-frame URL (for continuation generation). |
+| `--draft` | No| bool | Video task draft mode: faster / cheaper / lower quality. |
+| `--priority` | No| int | Video task scheduling priority 0-9. A higher value means higher priority.**Constrained by supported_params** — check whether the model supports it and the range in step 2 first (tested: seedance-2.0 / 2.0-fast support `[0,9]`). If the model does not support it, passing it will be rejected by validation. |
+| `--service-tier` | No| string | Video tasks: service tier. |
+| `--safety-id` | No| string | Video tasks: safety identifier passed in by the caller. |
+| `--execution-expires-after` | No| int | Video task server-side TTL (seconds). |
+| `--callback-url` | No| string | Video tasks: the server POSTs notifications to this URL for lifecycle events (created/running/succeeded/failed). |
+| `--wait` | No| bool | **Video tasks**: block until the task completes, **but not indefinitely** — once it passes `--timeout` (default 10m) it gives up and returns the still-running task id.**Default is false** — submission immediately returns a `task_id` for asynchronous polling (default behavior since 2.0; older versions waited synchronously by default). Giving up ≠ failing: the task keeps rendering server-side, so keep polling with `gen get <task-id>` and **do not re-run `+gen`** (that creates a second billed task). |
+| `--timeout` | No| duration | Video tasks: how long `--wait` blocks at most; accepts Go durations such as `20m` / `1h`. Defaults to `10m`; ignored without `--wait`.**Raise it for long videos**: in measurement, nearly half of seedance-2.0 requests did not finish rendering within 10m — hitting the cap returns "the task is still running", not a finished artifact. |
+| `--extra-body` | No| string (JSON object) | Video task forward-compatibility channel: pass a JSON object string. Its keys are merged into the top-level request body, so you can pass through newly added server-side parameters without upgrading arkcli. Example: `--extra-body '{"new_field":"value"}'` |
+| `--tools` | No| string (repeatable) | Tool switch. Currently supports `web_search`. |
+| `--save-to` | No| string | Local directory for saving generated artifacts. Default is `.` (current directory). Pass `--save-to=""` to explicitly disable auto-download. Download failures do not block the main process. |
+| `--no-gallery` | No| bool | Do not copy generated images into the product state gallery. This can also be disabled with `ARKCLI_NO_GALLERY=1`. |
+
+## Return values
+
+**Default output** (simplified):
+
+```json
+{
+  "kind": "image",
+  "model": "seedream-5-0-260128",
+  "status": "succeeded",
+  "output_url": "https://...",
+  "output_urls": ["https://..."],
+  "local_path": "/work/ark-gen.jpeg",
+  "local_paths": ["/work/ark-gen.jpeg"]
+}
+```
+
+- `output_url` / `output_urls`: TOS presigned URLs. They **expire after 24 hours**, so do not reference them long term.
+- `local_path` / `local_paths`: local absolute paths written after auto-download is triggered by `--save-to`. They are **persistent artifacts**, so use them instead of URLs when possible. These two parameters do not exist when auto-download is disabled (`--save-to=""`).
+- `task_id`: only available for video tasks.**Videos are asynchronous by default** — submission immediately returns this id + `status: queued`. Use `arkcli gen get <task_id>` (or `arkcli api arkruntime.get_content_generation_task --params '{"id":"<task_id>"}'`) to poll until `succeeded`, and then retrieve `output_url`. Use `+gen --wait` to block synchronously.
+
+**`--format json`**: outputs the full task object (without `local_path`).
+
+In addition to common parameters such as `id / status / output_url / ratio / resolution / duration / frames / generate_audio`, the full object of a video task also echoes extra parameters returned by the server (they appear as needed and are determined by the model and server):
+
+| Parameter |Description|
+|---|---|
+| `usage` | `{prompt_tokens, completion_tokens, total_tokens}` token usage telemetry |
+| `revised_prompt` | The prompt finally sent by the server to the model (after optimization / safety filtering). |
+| `subdivisionlevel` | Task subdivision level (note that the JSON key is word-style without underscores). |
+| `fileformat` | Output file format (also word-style without underscores). |
+| `safety_identifier` | Echo of the safety identifier passed in by the caller. |
+| `tools` | List of tool types actually used by the task, for example `["web_search"]`. |
+
+These parameters do not appear when the server does not return them (omitempty), and this does not affect extraction of core parameters such as `output_url` / `local_path`.
+
+## Common errors
+
+| Error | Cause | Fix |
+|------|------|---------|
+| `model is required` | `--model` is not specified. | A model name must be specified. |
+| `Error code: 404 - InvalidEndpointOrModel.NotFound` | `--model` is a model family name (such as `seedream-5-0` or `dreamina-seedance-2-0`), and no family-name alias is registered for that family. | Use `arkcli models get <name> --transform 'primary_version'` to get the version number, concatenate it into `<name>-<primary_version>`, and then pass it. |
+| Missing prompt | Positional parameter not provided. | The prompt is a required positional parameter. |
+| `image generation failed: InvalidParameter` | Parameter error such as too few pixels in the image size. This is common with sizes such as `1024x1024`. | Use `1920x1920` or larger. Add `--debug` to view the underlying error if needed. |
+| `role must be specified for image contents` | An image in a multi-image or video-bearing request has no role. | Add `first_frame:` / `last_frame:` / `reference_image:` to every image; do not rely on positional defaults. |
+| `reference media mode requires video role to be reference_video` | The request carries a video without a role. | Use `reference_video:` for the video and `reference_image:` for auxiliary images. |
+| First-frame and multi-reference modes are rejected together | Both `first_frame` and `reference_image` were sent. | Choose one mode: first/last frames, or all `reference_image`. |
+| The video task has no result for a long time. | Video tasks are **asynchronous** by default and return `task_id` + `status: queued` (**not a failure**). | Use `arkcli gen get <task_id>` to poll until `succeeded`. **Do not** submit `+gen` again (that creates a new task). Use `+gen --wait` if you want to wait synchronously. |
+| `warn: auto-download failed: ...`(stderr) | Failed to download `output_url` (network / 403, etc.). | Does not block the main process. `output_url` is still returned, and the user can manually recover with `curl -o file.ext "<output_url>"` (note the 24h validity). |
+
+## Notes
+
+- The prompt is a positional parameter. Put it at the end of the command, and it is recommended to wrap it in quotes.
+- Model name, model version, display name, Endpoint name, and `ep-*` ID are separate identifiers. Routing uses structured capability metadata, never a brand prefix.
+- `--input` is the data-driven multimodal entry point: image extensions go through the image channel, video extensions go through the video channel, and audio extensions go through the audio channel. Other extensions are **silently discarded** in video tasks (content-generation has no input_file slot) and are not recognized as reference images in image tasks.
+- Multiple `--input` values do not imply "the first image is always the first frame". Choose the mode first, then give every asset an explicit `first_frame:` / `last_frame:` / `reference_image:` / `reference_video:` / `reference_audio:` role. Omit the role only for single-image I2V when the model accepts positional inference.
+- For image generation, it is recommended to start from `1920x1920`. Sizes such as `1024x1024` may currently be rejected directly by the backend.
+- Image generation usually completes in a few seconds, while video generation may take tens of seconds to several minutes.
+- **Presigned URLs expire after 24h**: `output_url` can only be downloaded with HTTP `GET` within a short time (note that it is not `HEAD`, because the signature is bound to the method). For persistent storage, rely on `local_path` or download in time.
+- Default file name: when there is a `task_id` (video), the task_id is used; otherwise, `ark-gen` is used. The extension is inferred from Content-Type (`.jpeg` / `.mp4`, etc.). Duplicate names automatically get `-1`/`-2` suffixes.
+- For low-level troubleshooting or if you want to control the submission + polling cadence yourself: use the raw API directly: `arkcli api arkruntime.create_content_generation_task --params '{"model":"<id>","content":[{"type":"text","text":"<prompt>"},{"type":"image_url","image_url":{"url":"https://..."}}]}'` to get `id`, and then poll with `arkruntime.get_content_generation_task --params '{"id":"<id>"}'`.
+
+## References
+
+- [arkcli-gen](../SKILL.md) -- gen skill overview
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication and global parameters

package/skills/arkcli-gen/references/gen-meta.md

@@ -0,0 +1,154 @@
+---
+name: gen-meta
+description: Reference for arkcli gen get / list / delete and local gallery management commands.
+---
+
+# gen get / list / delete / gallery
+
+This is the "reconciliation side" of `+gen`: `+gen` submits generation tasks, while these three commands query task status afterward, list historical tasks, and delete completed tasks.
+
+## When to use
+
+- `gen get <task-id>`: You already have a `task_id` and want to retrieve the latest task status, including `output_url` / `usage` / `error`.**Once a task is `succeeded`, `gen get` automatically downloads the output to the local machine** (current directory by default, file name `<task-id>.mp4`), consistent with the persistence behavior of `+gen --wait`; `--save-to=""` can be disabled.
+- `gen list`: List asynchronous tasks under the current account, with filtering by `status` / `model` / `service-tier` / `task-id`.
+- `gen delete <task-id>`: Delete a completed task record. **Destructive and irreversible; must confirm with `--yes` when non-interactive**.
+- `gen gallery list`: Inspect locally archived `+gen` images and their disk usage.
+- `gen gallery clean --older-than 168h --yes` / `gen gallery clean --all --yes`: Remove local gallery files.
+
+## Modality coverage
+
+The endpoints behind these three commands (SDK `arkruntime.ListContentGenerationTasks` / `GetContentGenerationTask` / `DeleteContentGenerationTask`) are **modality-agnostic** on the server side:
+
+- Video-generation tasks created by `+gen` through a model or Endpoint.
+- Tasks created by 3D tasks (`Hyper3D-*`, `Hitem3D-*` model families).
+- Any asynchronous generation task submitted through `arkcli api arkruntime.create_content_generation_task`.
+
+However, **image tasks are not included** because they use the synchronous endpoint `arkruntime.generate_images`, which has no concept of a task list. This sync/async boundary comes from structured capability metadata, never from a model brand prefix.
+
+## Command quick reference
+
+```bash
+# 1. Submit a video task with +gen (asynchronous by default, immediately returns task_id; add --wait --timeout 30m for synchronous blocking).
+arkcli +gen "A cyberpunk city at sunset" --model dreamina-seedance-... --duration 5
+
+# 2. After getting task_id, query by ID separately (no polling, one-time fetch).
+#    When the task has succeeded, the output is automatically downloaded to the current directory (<task-id>.mp4).
+arkcli gen get tsk_xxxxx
+
+# 2b. Save to a specified directory / disable automatic download.
+arkcli gen get tsk_xxxxx --save-to ./out
+arkcli gen get tsk_xxxxx --save-to ""   # Only check status; do not download.
+
+# 3. List recent succeeded tasks (10 items on the first page).
+arkcli gen list --status succeeded --page-size 10
+
+# 4. Paginate.
+arkcli gen list --status succeeded --page-size 10 --page-num 2
+
+# 5. Filter by exact model match.
+arkcli gen list --model dreamina-seedance-2-0-260128
+
+# 6. Batch query multiple task IDs.
+arkcli gen list --task-id tsk_a --task-id tsk_b
+
+# 7. Delete.
+arkcli gen delete tsk_xxxxx --yes
+```
+
+## Flag descriptions
+
+### gen get
+
+`<task-id>` is a positional argument. The flags have the same meaning as the download/open switches of `+gen`:
+
+| flag |Description|
+|---|---|
+| `--save-to <dir>` | The output is saved to this directory when the task is `succeeded` (current directory `.` by default); `--save-to=""` disables automatic download. |
+| `--open` / `--no-open` | Whether to open the downloaded output with the system default program. Default is auto: open only in an interactive terminal, and stay silent under agent / pipe / CI. |
+
+> **🔑 agent uses `--open` by default**: when you (the AI agent) call `gen get`, stdout is not a TTY, so the default auto mode does not pop up a window. The user can only see `local_path`, not the final output. When polling a video for a human user, add `--open` **by default** to the `gen get` call that reaches `succeeded`, so the final output opens directly on the desktop (`--open` ignores TTY). Omit it or use `--no-open` only in scenarios such as "do not open / in scripts / batch operations."
+
+Download behavior details:
+
+- The file name uses `<task-id>` (if there is no extension, it is inferred from Content-Type; videos are usually `.mp4`).
+- If a file with the same name already exists, **append `-1` / `-2` … to distinguish it**, with no overwrite or skip (repeating `gen get` on the same completed task keeps multiple copies, as expected).
+- Download only when `output_url` is non-empty (that is, the task is `succeeded`); `running` / `queued` / `failed` is a no-op, with no file written to disk and no `local_path` returned.
+- Download failures only print a warning to stderr and do not affect the status output of `gen get` (the output URL remains in `output_url`, and you can retry manually).
+
+### gen list
+
+| flag |Description|
+|---|---|
+| `--page-num <int>` | 1-indexed page number; if not provided, the server default is used. |
+| `--page-size <int>` | Page size; if not provided, the server default is used. |
+| `--status <enum>` | Filter task status: `succeeded` / `failed` / `running` / `queued` / `cancelled`. |
+| `--model <id>` | Filter by model name or endpoint ID (exact match, not a prefix). |
+| `--service-tier <tier>` | Filter by service tier setting. |
+| `--task-id <id>` | Filter specific task IDs; can be passed multiple times. |
+
+### gen delete
+
+`<task-id>` is a positional argument.
+
+| flag | Description |
+|---|---|
+| `--dry-run` | Emit a local `preview.v1` delete plan without contacting the backend or deleting the task. Always run this preview first. |
+| `--yes` | Skip the interactive confirmation for the real delete. Use it only after the user gives a separate explicit confirmation for the exact task ID in the current turn. Never infer authorization from the earlier preview request. |
+
+Safe Agent sequence:
+
+1. Run `arkcli gen delete <task-id> --dry-run --format json` and explain the exact task that would be deleted.
+2. Wait for a separate explicit confirmation from the user.
+3. Only then run `arkcli gen delete <task-id> --yes --format json`.
+
+Do not add `--yes` to the preview command, do not treat a request to preview as delete authorization, and do not continue to the real delete without the second confirmation.
+
+## Output format
+
+- `gen get` reuses the `VideoTask` structure of `+gen`: `{id, model, status, output_url, ratio, resolution, duration, ...}`; when the task is `succeeded` and automatic download succeeds, `local_path` is also returned (the absolute path on disk; this parameter is omitted when `--save-to=""` is used or the task has not succeeded).
+- `gen list` returns `{total: <int>, items: [<item>, ...]}`; each `item` is the raw JSON form of an SDK list item. **Note the following 3 differences from `gen get`**:
+  - The error parameter is called `failure_reason`, not `error`.
+  - **Does not include `resolution` / `ratio` / `duration`** (to get these parameters, call `gen get` again).
+  - The JSON keys for the two parameters `subdivisionlevel` / `fileformat` are word-style (no underscores), reflecting the SDK wire truth.
+- `gen delete` returns `{id, deleted:true}`. The server has no response body; this is synthesized by arkcli.
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `gen get` / `gen delete` reports `missing task id`. | The positional arg was not provided. |
+| `gen list` returns empty `items[]`. | The filter is too strict, or there are indeed no tasks under the current account. |
+| `gen get` cannot get `output_url`. | The task is still `running` / `queued`; check the `status` parameter. |
+| Using the ID returned by an image task with `gen get` reports not found. | Images use a synchronous endpoint, not a task list; the usage is mismatched. |
+
+## Relationship with the raw API
+
+| Subcommand | Equivalent raw API |
+|---|---|
+| `gen get <id>` | `arkcli api arkruntime.get_content_generation_task --params '{"id":"<id>"}'` |
+| `gen list ...` | `arkcli api arkruntime.list_content_generation_tasks --params '{"page_num":1,"filter":{...}}'` |
+| `gen delete <id>` | `arkcli api arkruntime.delete_content_generation_task --params '{"id":"<id>"}'` |
+
+### gen gallery
+
+`gen gallery` only touches local state and does not call the control plane:
+
+```bash
+arkcli gen gallery list
+arkcli gen gallery clean --older-than 168h --yes
+arkcli gen gallery clean --all --yes
+```
+
+| flag | Description |
+|---|---|
+| `--older-than <duration>` | Delete files older than this duration (Go duration such as `168h`; `30d` is not accepted). |
+| `--all` | Delete every regular file in the gallery; mutually exclusive with `--older-than`. |
+| `--yes` | Skip the interactive confirmation; required in non-interactive mode. |
+
+CLI subcommands are human-friendly wrappers around the raw API; the commands are shorter and the flags are more intuitive. The raw API is still the fallback channel.
+
+## Use with `+gen`
+
+- When `+gen` itself times out while polling, it returns `task_id` and a hint. Continue tracking with `gen get <task-id>`, which is more cost effective than rerunning `+gen` (rerunning creates another new task and consumes quota again). The `gen get` call that polls to `succeeded` downloads the output locally along the way, so you do not need to manually curl `output_url`.
+- Asynchronous submission (without `--wait`) + polling with `gen get` is the mainstream video workflow: `arkcli +gen ... --modality video` gets `task_id` → repeatedly run `gen get <id>` until `succeeded` → the output is automatically saved locally. With `--wait`, it is the synchronous blocking version; the two paths have the same persistence behavior — **but `--wait` is capped**: it blocks at most `--timeout` (default 10m), so raise it explicitly for long videos (e.g. `--timeout 30m`). When the cap is hit the task is still running: keep polling with `gen get <task-id>` and **do not re-run `+gen`**.
+- `gen list` is the only entry point for checking "whether that task I submitted earlier actually exists"; if `+gen` does not get a normal return after submission, it is recommended to run `gen list --status running` first.

package/skills/arkcli-gen/references/image-stream.md

@@ -0,0 +1,105 @@
+---
+name: image-stream
+description: arkcli +gen --stream streaming image output. One image_generation.* event JSON per line (NDJSON), suitable for incremental preview / visualizing progress / using jq to extract each frame URL.
+---
+
+# +gen --stream (image streaming)
+
+By default, `+gen` waits synchronously until the entire generation finishes. `--stream` switches the CLI to NDJSON output and writes the server-side SSE streaming events to stdout as-is, one event per line. Suitable for:
+
+- Multi-image generation scenarios (`--image-count >1`) where you want to process the first image as soon as it is available.
+- Connecting to jq / script pipelines for incremental preview or parallel downloads.
+- Debugging server-side streaming behavior.
+
+## Scope
+
+**Image tasks only**. Video tasks use the async task + polling model (`+gen` polls by itself) and have no SSE channel. Passing `--stream` with a video model will be intercepted by `+gen` before the request is sent:
+
+```
+--stream only applies to image generation tasks
+hint: remove --stream (video tasks use async polling, not SSE),
+      or pass --modality image with an image-capable model / endpoint
+```
+
+## Event protocol
+
+The underlying implementation uses SDK `arkruntime.Client.GenerateImagesStreaming`, with three event types:
+
+| Event type | When to send | Parameters |
+|---|---|---|
+| `image_generation.partial_succeeded` | When each image finishes generating | `url` / `b64_json` / `size` / `image_index` / `model` / `created` |
+| `image_generation.partial_failed` | A single image fails to generate (does not necessarily terminate the stream). | `error.code` / `error.message` |
+| `image_generation.completed` | Stream ends | Optional `usage{generated_images, output_tokens, total_tokens}` / `tools[]` |
+
+The CLI outputs one `ImageStreamDelta` JSON per line (service-layer view). Key parameters:
+
+```json
+{
+  "event_type": "image_generation.partial_succeeded",
+  "model": "seedream-5-0-260128",
+  "created": 1700000000,
+  "image_index": 0,
+  "url": "https://...",
+  "size": "1024x1024"
+}
+```
+
+Note:
+- For `partial_failed`, `error.code/message` are two flat parameters in ImageStreamDelta: `error_code` / `error_message`.
+- For the `completed` event, `usage` / `tools` are renamed to `final_usage` / `final_tools` in ImageStreamDelta.
+- The `b64_json` (Base64 string image) parameter appears only when ResponseFormat is `b64_json` (default: `url`).
+
+## Command quick reference
+
+```bash
+# 1. Stream-generate a single image (process it as soon as you see the first frame).
+arkcli +gen "neon kitten" --model seedream-5-0-260128 --stream
+
+# 2. Stream-generate 3 images and get the URLs in order.
+arkcli +gen "5 different futuristic cars" \
+  --model seedream-5-0-260128 \
+  --image-count 3 --stream \
+  | jq -r 'select(.event_type=="image_generation.partial_succeeded") | .url'
+
+# 3. Streaming + decode Base64 (first switch b64_json to the stream).
+arkcli +gen "blue laptop" \
+  --model seedream-5-0-260128 --stream \
+  | jq -r 'select(.b64_json != "") | .b64_json' \
+  | base64 -d > out.png
+
+# 4. Monitor error events + final usage.
+arkcli +gen "..." --model ... --stream \
+  | jq 'select(.event_type=="image_generation.partial_failed" or .event_type=="image_generation.completed")'
+```
+
+## Relationship with `--save-to`
+
+`--save-to` is the "automatic download" feature on the synchronous path. `--stream` **does not trigger automatic downloads**.
+
+Reason: the purpose of streaming is to let users process output incrementally. The CLI should not write files to disk in parallel and interfere. When you need both disk output and streaming monitoring, pipe the streaming output to your own download script (see example 3 above).
+
+## Relationship with the raw API
+
+`+gen --stream` is equivalent to:
+
+```bash
+arkcli api arkruntime.generate_images_stream \
+  --params '{"model":"...","prompt":"...","stream":true,"response_format":"url"}'
+```
+
+However, the raw API cannot receive the ParseAssetRefs / collapseImageAssets / modality routing capabilities from the `arkcli +gen` layer. For normal use, use `+gen --stream`. Use the raw API only when debugging SDK parameters or testing server-side behavior.
+
+## Scenarios where streaming is not supported
+
+| Scenario | Why | Alternative |
+|---|---|---|
+| A model or Endpoint resolved as video (or explicit `--modality video`) | Video uses the async task + poll model and has no SSE channel. | Do not pass `--stream`; use the default polling of `+gen`. |
+| Synchronously wait for accumulated results | In `--stream` mode, stdout is an NDJSON stream and does not output the accumulated GenerateOutput. | Do not pass `--stream`; use the default synchronous path. |
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `--stream only applies to image generation tasks` | Structured metadata resolves the model/Endpoint as video, or `--modality video` is explicitly specified. |
+| The first line of streaming output is `partial_failed`, followed by no further output. | The upstream request actually failed. Check the `error_code` parameter. This is especially common with small sizes such as `--size 1024x1024`. |
+| The `completed` event is not shown. | When `--image-count 1`, the server may not send `completed`; the single image is the end. It is sent only for multiple images. |