arkcli-gen

arkcli generation workflow (+gen)

CRITICAL — before starting, MUST first use the Read tool to read ../arkcli-shared/SKILL.md(authentication gate, model lookup fallback, shared safety rules).

CRITICAL — real generation is a workflow, not guessing one command: follow Step 1 → Step 2 → 必要时 Step 2.5 → Step 3 to execute. The only exception is when the user only asks for --dry-run : all local, do not first run online Resources / Models / Usage admission; keep online unknown items as unresolved. Before executing, be sure to read references/arkcli-gen.md。

CRITICAL — when the user explicitly provides an API Key / Base URL / Endpoint, MUST first read ../arkcli-shared/references/execution-context.md. The authoritative metadata of an explicit Endpoint takes precedence over the current profile.

Additional Volcano constraint: do not treat the user-provided Endpoint as a plan model call just because the active profile is Agent/Coding Plan.

Agent quick execution order

First break the user's request into acceptance-checkable items, then proceed in order through resources, capabilities, whole-batch budget, execution, and finished-product checks. Before executing, read references/intent-and-validation.md: it specifies defaults for incomplete intent, parameter combinations, credential error triage, and finished-product acceptance. The parameter table is candidate capabilities and does not mean every model supports them. When the user has explicitly asked for an image or video, the generation command explicitly includes --modality image|video; do not let name resolution override the user's intent. Only use materials provided by the user in this turn or explicitly authorized for reuse; do not arbitrarily add extra reference images/videos from historical directories, old tasks, or similar filenames.

Before finished-product acceptance: host visual input admission

The fact that the generation model can produce images does not mean the host model driving the current Agent can see images.The Read tool description saying it supports images is also not proof of the current host model's visual capability. When the current session has no reliable visual capability declaration or verified compatibility, treat it as "not admitted":Do not natively Read images, videos, or extracted frames, and do not probe whether they can be read using the finished product. This Skill, reference documentation, and text such as JSON can still be Read normally.

When there is already a compatible and authorized visual tool, or an admitted visual model under the same entity with unchanged billing path, analyze the actual media according to the corresponding Chat/Understand Skill, and return only the text result to the host; do not automatically switch host, Profile, or Key.
When there is no such entry point, complete structural checks such as files/decoding/size/duration and deliver the existing finished product, clearly stating "visual semantics not verified"; do not claim to have seen it or that it fully complies. Do not add unauthorized paid calls just to supplement acceptance.
If after successful generation the host image-reading errors, that is acceptance/delivery failure; keep the finished product, do not resubmit generation or rotate the business Key.

Anti-trigger signals

Describe or analyze an existing image rather than generate/edit → arkcli-chat or arkcli-understand。
with a fixed output form Only query resources, capabilities, usage → use the corresponding read-only Skill; do not submit a generation task.

Why it is a workflow (core, understand before executing)

When the user says "generate a video/an image", it is essentially at leastthree independent things, and they must be done in order; batch or multi-stage tasks also require first confirming that the whole batch can be completed:

① 本次资源从哪里来           ── 用户显式 Endpoint 优先；否则看当前 profile
② 该模型支持哪些参数          ── 不查就传参 = 瞎猜 = 被校验拒/被后端拒
②.5 多候选/多阶段额度与任务数 ── 先算完整批次，额度已耗尽就不启动半批任务
③ 按可用参数真去生成          ── 每个请求只提交一次并立即保存 task_id

Compress these three steps into "directly +gen guessing a command" is precisely the source of failure: if the model name form is wrong, you get a 404, and if the parameter model is unsupported, it will be rejected.

Modality resolution hard contract

+gen 's production calls resolve capabilities according to the following fixed priority:

explicit --modality > output_modalities > task types > unknown

When passing a versioned model ID directly, read the output_modalitiesreturned by ArkModels; if missing, then read the FoundationModel's task_types / filter_task_types。
When passing ep-* , first read the Endpoint's ModelReference.FoundationModel(name, version), then exactly match the above structured metadata of the same-version model.
The model name and DisplayName are only used to locate the model and do not participate in modality determination. Do not infer image/video from seedream、seedance or any domestic/overseas brand prefix.
When structured metadata is missing or conflicts with each other, return unknown, prompting the user to explicitly pass --modality image|video; silent guessing is prohibited.
+gen --dry-run is a purely local Client Preview: it does not read Endpoint/model metadata, does not call the generation API, and does not download or open files. Explicit --modality is the most reliable; known seedream/seedance model names can be determined locally, and other models or Endpoints must explicitly pass --modality image|video. The execution context that can only be completed when online will be indicated with unresolved and fidelity=partial .

Applicable scenarios

"generate an image" / "text-to-image" / "draw an X"
"generate a video" / "text-to-video"
image-to-image / image-edit / add reference image; image-to-video (I2V); reference video (R2V); reference audio
"use this image as the first frame to generate a video" / "keep the motion of this reference video"

Workflow overview

用户意图: "生成 X"
  │
  ▼ Step 1【强制】解析本次资源
  │     用户给 Endpoint → arkcli resources resolve <ep-id>
  │     未给 Endpoint   → arkcli resources list --modality image|video
  │
  │     当前 profile 可用资源：
  │     platform    → 列 EP (ep-xxx)           ┐
  │     agent-plan  → 列视觉模型名              ├─ 选一个，记为 $MODEL
  │     coding-plan → 列 EP (借道 platform)     ┘
  │
  ▼ Step 2【强制】查可用参数  ──► models get（EP 用 resolve 得到的绑定模型查能力）
  │     模型名 + 有 sp → **只能**用列出的参数，取值落 min/max/enum 内
  │     模型名 + sp 空(未配置或当前不可解析) → +gen 自动套 modality 兜底默认(video 720p/5s; image 不填 size)
  │     EP(ep-xxx)            → 可解析绑定则查精确版本；不可解析则说明未知，不猜支持
  │
  ▼ Step 2.5【批量/多阶段】额度预检 ──► plan/free-quota 快照；记录完整 create 数
  │
  ▼ Step 3 据可用参数生成  ──► arkcli +gen --model $MODEL [Step2 允许的参数] "prompt"
  │
  ▼ Step 4【结果处理】
        视频 = 异步：返回 task_id + status=queued(**不是失败!**) → arkcli gen get <task_id> 轮询;轮到 succeeded 自动下载到本地(local_path);要同步阻塞加 --wait(有上限,默认 10m,长视频配 --timeout 30m)
        图片 = 同步：直接返回 output_url + local_path

Step 1 [Mandatory] Resolve the explicit Endpoint, or list the resources available to the profile

When the user has already explicitly provided an Endpoint, do not first override it with the active profile's model pool:

arkcli resources resolve "$ENDPOINT" --format json

Read generation_modality to determine image/video;image_or_video or unknown , then combine with user intent, and explicitly supplement --modality。
Read resource_region; when Endpoint + explicit API Key is given and no Base URL is provided, the CLI uses that region to derive the platform Base URL.
Do not guess the modality based on the Endpoint ID or the seedream / seedance substring in the bound model name.
Explicit Endpoint + API Key is a temporary call; it does not switch the active profile, nor write the values back.
The ep-* explicitly provided by the user is the resource for this call; do not ignore it and switch to the plan default, and do not mistakenly pass resources resolve 's positional argument as the model name. If this Endpoint has been authorized by the user in this round for pay-as-you-go fallback, when the plan quota is insufficient you may return here to redo the capability check, but still do not modify the Profile/default.

When the user does not provide an explicit Endpoint, then list resources by profile:

# 按目标模态列；输出 items[].id 就是可作 --model 的候选
arkcli resources list --modality video   # 或 image

Platform differences (resources list already automatically routes by profile; you only need to read items)：
- platform profile → items areinference access points EP（ep-xxx), each EP is internally bound to one model
- agent-plan / agent-plan-team → items areplan vision model names; use the corresponding personal/team seat Key
- coding-plan / coding-plan-team → no in-plan vision model; generation uses platform Endpoint + pay-as-you-go API Key. The team seat Key cannot be used for this pay-as-you-go request
is_default: true marks the current default for that modality; when the user has not specified one, use it first
Then verify invocable / required_overrides / data_plane / credential_kind. Default or visible does not mean the current credentials can call it; do not automatically switch Profile, rotate Key, or modify default for generation.
Select one id, record it as $MODEL, and use it throughout Step 2/3
When the user has explicitly given a model name, you may use resources list to verify compatibility of the current lane; when the user has explicitly given an EP, only first resources resolve, do not override it with the list/default. If the model differs from the default, handle it according to ../arkcli-shared/references/profile-defaults.md "Default drift detection and promote nudge"

Step 2 [mandatory] Check the available parameters of $MODEL

arkcli models get "$MODEL" --transform supported_params

$MODEL is the model name: obtain that model's supported_params list (each item includes name / type / support / min / max / enum / required / default / description）。
- MUST: Step 3 may only use the parameters support=true here, and the values must fall within the min/max/enum range. Parameters not in the list (or support=false) will be +gen rejected if passed.
- MUST：description must be read item by item, and cannot be skipped as comments. In an actual test of 74 parameter entries, description fill rate 100%, while min/max is only 9%,enum is only 19% — most structured fields that look "present" are empty; the only one that is fully filled is the carrier of conditional constraints. When "only allowed / only supported / must / not supported / recommended / otherwise" appears,it is a hard constraint, not a hint. Four typical types:
- - Value range —— duration of min=4 max=30 only gives the interval,description only then adds "the value is 4-30 or -1」。-1 falls outside the interval yet is legal,default=-1 confirms it:default is a legal value declared by the catalog itself; when it conflicts with min/max , default prevails（+gen Local validation also allows it on this basis, with no need for --force）。
- - Conditional subset —— ratio of enum lists 7 values, but "video editing, video extension...only allows adaptive", that is, under a certain condition enum has only one legal value left.
- - Cross-parameter dependency —— omni_reference_task_type of description gives auto/reference/edit/extend four valueseach's ratio/duration constraints;background=transparent depends on the format and number of reference images.
- - Alternative —— frames of description says "please use duration", that is, what to replace it with when that parameter is unavailable.
- When the value conflicts with description , or local validation rejects a value declared legal by the catalog,preserve the conflict evidence(model name,name, catalog original text, CLI error) before deciding the next step; do not silently change the value or switch models.
- You may directly use the model id selected in Step 1：models get will be normalized to the canonical hyphenated name according to DisplayName. But normalizationonly recognizes the single form "dot form == lowercase DisplayName", not "dots are always usable" — going out of bounds will not found：
  - ✅ doubao-seedance-2.0-fast(DisplayName is Doubao-Seedance-2.0-fast）→ doubao-seedance-2-0-fast
  - ✅ doubao-seedream-4.5 → doubao-seedream-4-5
  - ❌ doubao-seedream-5.0 — this family's DisplayName is actually Doubao-Seedream-5.0-lite, the bare family name does not match
  - ❌ doubao-seedream-5.0-pro-260628 —— dot + date snapshot: DisplayName does not include a date, so it does not match
  rule: names with a date snapshot always use the hyphenated form (doubao-seedream-5-0-pro-260628); the dot form is only used for family names / variant names without a date. If it still reports not found , use arkcli models search <族名> to verify the canonical name; do not try guessing the dot position.
- The model is found but supported_params is empty / null → this version has no parameter catalog configured, or the upstream catalog is currently unparsable; if stderr has warn: model supported_params enrichment failed: ..., keep that warning for troubleshooting.Do not manually guess parameters：+gen will automatically fill in the parameters you did not specify using the built-in modality fallback defaults (video: resolution=720p / duration=5 / ratio=adaptive);For image tasks, do not fill in size — the canvas is determined jointly by the aspect ratio described in the prompt and the server-side default; hardcoding a 1:1 constant will override the ratio already stated in the prompt. When you need a fixed canvas, explicitly pass --size. When the control-plane query fails (as opposed to "the model simply has no catalog configured"), stderr will also have a warn: ... indicating that parameter validation was not performed this time — it goes to stderr rather than JSON, and it also appears when generation fails. Go directly to Step 3.
$MODEL is an EP (ep-xxx）: do not hand the EP itself to models get. Use the authoritative binding from Step 1: for FoundationModel query model_name + --version <model_version>; for CustomModel you may only use base_model_* to query lineage capabilities, and you must not rewrite the real model_id or call the EP. In case of warning/ambiguity, state that the capability is unknown and do not guess support based on the name.
- The model ID obtained from the capability query is only used for querying; Step 3 still passes the original EP. The CLI currently does not force-fill modality fallback parameters for the EP, nor does it replace the server-side final validation.

Step 2.5 [batch or multi-stage tasks] check the full budget before submission

A single image/video request does not create an extra "test Key" task; when batch candidates, long-video segmentation, continuation chains, etc. will create multiple billable tasks, you must, before the first +gen , list the total number of candidates, the number of stages per candidate, the theoretical total number of creates, and the stage dependencies. When it can be done with one native 30-second task, do not arbitrarily split it into two 15-second tasks before the model/Endpoint has been verified.

For batch or multi-stage visual tasks on Agent Plan / Agent Plan Team, read the current Profile and then take a quota snapshot:

arkcli usage plan --format json
arkcli usage balance --type free-quota --modality ComputerVision --page-all --format json

These two results are pre-submission snapshots, not quota reservations; judge only by the relevant buckets for the currently selected lane/model, and do not mix in the quota of another product.
When the relevant monthly/weekly/session bucket or model free quota is clearly exhausted, do not start a batch that can only be half completed. If the user has explicitly authorized a certain postpaid Endpoint in this round, then first resources resolve that EP and redo Step 2 according to its exact binding; otherwise explain the shortfall and stop, and do not automatically switch Profile, Key, default, or billing path.
If the response does not provide a computable mapping from "seconds/number of candidates → quota", you can only report "currently not exhausted but the whole batch cannot be guaranteed"; you must not fabricate an exact remaining generatable quantity. A 429 also cannot be guessed as a concurrency limit based on the status code alone.

The control plane resolve/list can only prove that the resource metadata is compatible with the context; it cannot prove that the data-plane API Key is currently valid. When there is no no-billing Key probe, usethe first task that was going to be delivered anywayas data-plane admission: only after successfully obtaining the task_id/image result do you continue with the remaining batches; 401/403/quota errors stop according to the original evidence. It is forbidden to generate another test image, and it is also forbidden to rotate Keys or loop through different billing paths after a failure.

Step 3 Generate based on available parameters

# 文生图 / 文生视频
arkcli +gen --model "$MODEL" --modality image "<prompt>" # 用户要视频时改为 video

# 带 Step 2 确认过的参数（示例：视频 1080p + 优先级 9，前提是 supported_params 列了它们）
arkcli +gen --model "$MODEL" --resolution 1080p --priority 9 "<prompt>"

# 图生图 / 图生视频 / 参考素材：--input 可重复
arkcli +gen --model "$MODEL" --input @ref.jpg "<prompt>"

Full parameter set, multimodal --input rules, newly added --n/--priority/--wait/--timeout see references/arkcli-gen.md
The modality of the Endpoint is automatically resolved from the authoritative metadata in Step 1; only when the metadata is unknown / image_or_video and the user intent is still insufficient do you require an explicit --modality。
Artifacts are by default automatically downloaded to CWD(or --save-to <dir>); the local_path in JSON is a persistent artifact, the presigned output_url expires in 24h, prefer referencing local_path。--save-to="" off
Automatically open the artifact with the system default program: by default it opens only when stdout is an interactive terminal (a person running it directly in a terminal)—when an agent / pipe / CI captures stdout (non-TTY),do not pop up a window, and only return local_path。--open force open,--no-open force do not open. It only takes effect for local files that have already landed (when an asynchronous video has not --wait there is no local file and it does not open); for multiple artifacts, only open the first several
🔑 You are an agent, and by default you have --open: when you (an AI agent) call arkcli, stdout is taken over by you = non-TTY, and the default auto will not pop up a window; the user can only see the file path and cannot see the finished product.So that the user can directly see the generated image/video, for any +gen that produces images/videos for a real person and any succeeded polled to gen get, by default add --open（--open ignore TTY and force opening on the user's desktop). The only exceptions are: the user explicitly says "don't open / in a script / batch / don't pop up a window", or a batch scenario with more than 4 images at once → in this case omit --open or explicitly --no-open。

Step 4 [Result handling] Video asynchronous / image synchronous

Modality	Default behavior	How you should read the result
Video	Asynchronous: immediately returns `task_id` + `status: queued`	`queued` is not a failure. Use `arkcli gen get <task_id> --open` to poll until `succeeded`——this time `gen get` will conveniently download the artifact locally and bring back `local_path`(default CWD,`<task-id>.mp4`），`--open` lets the finished product pop up directly on the user's desktop (you are an agent, non-TTY; if you do not add it, there will only be a path); there is no need to manually curl `output_url`；do notresubmit `+gen`just because you did not get the video (it will create a new task)
Video + `--wait`	Synchronous: blocks until completion and then returns,but if it exceeds `--timeout`(default 10m) it gives up	`arkcli +gen ... --wait --open`, directly take `output_url` / `local_path` and pop up the finished product.For long videos, first increase `--timeout`(e.g. `--timeout 30m`): In testing, nearly half of seedance-2.0 requests cannot finish rendering within 10m; when the time limit is hit, what is returned is "task still running + task id" rather thana failure, just keep `gen get <task-id>` polling,do not rerun `+gen`
Image	Synchronous: directly return `output_url` + `local_path`	`arkcli +gen ... --open` to let the image pop up directly for the user to see

⚠️ Behavior change (2.0): Video tasks have by default changed from "automatically wait for completion" to "return task_id immediately upon submission". If you need the old synchronous blocking behavior, explicitly add --wait。

⚠️ --wait has an upper limit: it blocks for at most --timeout(default 10m), and returns when the time is up. Video rendering often takes longer (in testing, nearly half of seedance-2.0 cases exceed 10m), sofor long videos, explicitly --timeout 30m. The JSON returned when the time is up is type: timeout + with task id error—thisis not a generation failure, the task is still rendering on the server; follow the gen get <task-id> in the hint to continue polling,never rerun +gen(it will create another billable task).

Polling contract for scripts with an existing task

gen get --format json of status is an object, the terminal state must be read from .status.phase, not by comparing the entire .status with a string. When generating a shell polling script, you must follow:

During the polling phase, use arkcli gen get "$TASK_ID" --save-to="" --format json to disable automatic download, and only read the status each round.
PHASE=$(printf '%s' "$RESULT" | jq -r '.status.phase // empty'), then do an explicit branch on succeeded / failed / cancelled .
succeeded , at most execute once more with the target --save-to of gen get to download the artifact, then immediately break；failed / cancelled report status.message or error then immediately break。
queued / running only then sleep and continue; unknown phase or gen get itself failing should stop and report an error, and must not be treated as running in an infinite loop.
The entire script only checks the existing task; it is forbidden to re-execute in the polling or failure branch +gen。

Quick decision

User wants one-step image/video output → use this workflow (Step 1→2→3)
User has not decided on a model yet → Step 1 resources list lists the current profile candidates; if the model family is uncertain → go to ../arkcli-models/SKILL.md
Image-to-image / reference material → Step 3 add --input @<file>(repeatable)
After video generation, "no video seen" → most likely asynchronous queued, use arkcli gen get <task_id> --open to poll; on the round when it reaches succeeded it will automatically download locally (see the returned local_path) and pop up the finished product, do not resubmit
For images/videos of real people, add by default --open → you are an agent (non-TTY); if you do not add it, the user can only see the path, not the finished product; only omit it for "do not open / in scripts / batch >4 images" or --no-open
Video continuation → reference_video accepts local @<path>(the CLI automatically uploads to TOS and then submits with a presigned URL) or https://...; local material upload requires the account to have TOS enabled; if not enabled, it will fail before submission and provide an activation entry. ratio follows the exact model/EP supported_paramsvalue by value, and does not unconditionally force adaptive

Advanced flag natural language trigger phrase table

What the user says	Corresponding flag / command
"Open it directly after generating / open it for me / pop it up as soon as it's out"	`arkcli +gen --open`(Force opening with the system default program; by default it is already opened automatically in an interactive terminal)
"Don't open automatically / no pop-ups / I'm running it in a script so don't open it"	`arkcli +gen --no-open`(Force not to open)
"Preview / don't actually send / just look at the parameters / dry run / trial run / take a look first"	`arkcli +gen ... --dry-run --format json`; verify `steps`、`unresolved` and `fidelity`, and do not treat the partial preview as server-side validation
"Don't download / only want the URL / don't save locally / turn off automatic download"	Explicitly add `--save-to=""`to the command; even if it is also `--dry-run` it must be retained so that the preview can verify the intent to disable downloading during actual execution
"Draft / quick preview / the faster the cheaper / save money and take a look first"	First distinguish between "only look at the request" and "actually generate a low-cost draft". For the former use `--dry-run`; for the latter, add `draft` only when `--draft=true`supports it. When it is not supported, explain the limitation, and do not pass off shortening the duration as draft mode
"Fixed shot / camera doesn't move / lock the camera / only capture changes in light and shadow"	Always keep it in the prompt; add `camera_fixed` only when `--camera-fixed=true`supports that value. When it is not supported, the visual constraint can be expressed in the prompt, but mechanical locking cannot be guaranteed; acceptance should check background/camera changes across frames
"No watermark / don't want a watermark / turn off the watermark"	After confirming support, explicitly `--watermark=false`; omitting it may use the server-side default, and bare `--watermark` means true
"Force execution / skip validation / I know it's not supported but I want to try it"	`arkcli +gen --force`
"Coherent multiple images / in order / unified style / consecutive images"	First distinguish between multiple independent files and one multi-panel image; for multiple files, use `--image-count N --sequential auto`when the capability supports it, and do not use a bare `--sequential`
"My previous tasks / generation history / task list / task status"	`arkcli gen list`(List all asynchronous generation tasks)
"Is that task done yet / check progress / check status"	`arkcli gen get <task_id>`

Command overview

Command	Role
`arkcli resources list --modality image\|video`	Step 1 — Models/EPs available to the current profile
`arkcli resources resolve <endpoint-id>`	Step 1 (explicit EP) — Authoritatively resolve modality, workflow, and region
`arkcli models get <model> --transform supported_params`	Step 2 — Check the available parameters of the model
`arkcli +gen`	Step 3 — Generate according to the available parameters
`arkcli +gen --stream`	Streaming NDJSON output for image tasks
`arkcli gen get <task-id>`	Step 4 — Poll/query asynchronous video tasks
`arkcli gen list`	List/filter asynchronous generation tasks
`arkcli gen delete <task-id>`	Delete asynchronous generation tasks

Common fallbacks

Model name reports not found → models get normalization only covers "dotted form == lowercase DisplayName", not that any dotted form is usable; names with date snapshots use the hyphenated form (such as doubao-seedream-5-0-pro-260628). Keep the original error, and within the same identity and scope use arkcli models search <族名> to verify the canonical name, version, and visibility; do not conclude from this error alone that the model has been retired.
Explicitly reports has not activated the model / model not activated → read arkcli-models-activate.md, keep the original model, user assets, and generation intent, and enable it through the host's authorization flow; after success, return to this generation task without changing identity, Key, or model. If a task ID already exists, check the original task status first; do not submit it again. If enabling reports BalanceNotEnough, report the actually returned balance/eligibility threshold and stop looping; do not hard-code a top-up amount, and do not interpret every inactive error as insufficient funds.
Parameter rejected (param_not_supported) → compare against Step 2's exact version catalog and the actual parameters; if the catalog shows support but the CLI rejects it, preserve the conflicting evidence, and do not arbitrarily switch the call ID, delete the user's hard requirement, or use --force to bypass it. Use --force。
- Exception: when the catalog itself declares the value valid, first determine whether it is a CLI validation bug rather than the user's parameter being wrong. The criterion is default: if the value equals the parameter's default but is rejected by min/max , then it is a conflict between local validation and the upstream catalog (default necessarily occurs when it falls outside its own min/max ). Such conflictsshould not be concealed with --force Conceal— first report the original conflict to the user (model name / parameter name / catalog min·max·default / CLI error), and let the user decide whether to fix the CLI or explicitly require --force. Using --force to bypass it permanently disguises "the CLI has a bug" as "the parameter was submitted," and the next user will hit it again.
Content blocked by moderation（ContentRiskBlocked / *SensitiveContentDetected / sensitive / copyright match) → this is not a parameter issue, and--force cannot bypass it either; adjust the sensitive content in the prompt / input assets and retry. For a structured blocking reason + remediation guidance, go to ../arkcli-doctor/SKILL.md 's arkcli doctor error <code>(full coverage of the 5 video-generation blocking subtypes)
Authentication error → go to ../arkcli-auth/SKILL.md

Reference

arkcli-shared — Authentication and global parameters (required reading)
arkcli-models — Step 2 Model query/supported_params detailed explanation
references/arkcli-gen.md — +gen all parameters + multimodal + asynchronous semantics