Arkcli Gen

arkcli 生成工作流（+gen）

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md（认证闸门、模型查找回退、共享安全规则）。

CRITICAL — 这是一段三步工作流，不是单条命令。生成图/视频 MUST 按 Step 1 → Step 2 → Step 3 顺序执行。禁止跳过 Step 1/2 直接 +gen：会因模型名形态不对（404）或传了模型不支持的参数而失败。执行前务必读 references/arkcli-gen.md。

CRITICAL — 用户显式给出 API Key / Base URL / Endpoint 时，MUST 先读 ../arkcli-shared/references/execution-context.md。显式 Endpoint 的权威元数据优先于当前 profile。

火山额外约束：不要因为 active profile 是 Agent/Coding Plan 就把用户给出的 Endpoint 当套餐模型调用。

为什么是工作流（核心，先理解再执行）

用户说"生成一个视频/一张图"，本质是三件独立的事，必须按序：

① 本次资源从哪里来           ── 用户显式 Endpoint 优先；否则看当前 profile
② 该模型支持哪些参数          ── 不查就传参 = 瞎猜 = 被校验拒/被后端拒
③ 按可用参数真去生成

把这三步压成"直接 +gen 猜一条命令"，正是失败之源：模型名形态不对会 404，参数模型不支持会被拒。

模态解析硬契约

+gen 的生产调用按以下固定优先级解析能力：

explicit --modality > output_modalities > task types > unknown

• 直接传版本化模型 ID 时，读取 ArkModels 返回的 output_modalities；缺失时再读取 FoundationModel 的 task_types / filter_task_types。
• 传 ep-* 时，先读取 Endpoint 的 ModelReference.FoundationModel(name, version)，再精确匹配同版本模型的上述结构化元数据。
• 模型名与 DisplayName 只用于定位模型，不参与模态判断。不要从 seedream、seedance 或任何国内/海外品牌前缀推断 image/video。
• 结构化元数据缺失或互相冲突时返回 unknown，提示用户显式传 --modality image|video；禁止静默猜测。
• +gen --dry-run 是纯本地 Client Preview：不读取 Endpoint/模型元数据、不调用 生成 API，也不下载或打开文件。显式 --modality 最可靠；已知 seedream/seedance 模型名可本地判断，其他模型或 Endpoint 必须显式传 --modality image|video。在线才能补齐的执行上下文会以 unresolved 和 fidelity=partial 明示。

适用场景

• "生成一张图" / "文生图" / "画一个 X"
• "生成一个视频" / "文生视频"
• 图生图 / image-edit / 加参考图；图生视频(I2V)；参考视频(R2V)；参考音频
• "用这张图当首帧生成视频" / "保持这个参考视频的运动"

工作流总览

用户意图: "生成 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【强制·EP 除外】查 $MODEL 可用参数  ──► arkcli models get $MODEL --transform supported_params
  │     模型名 + 有 sp → **只能**用列出的参数，取值落 min/max/enum 内
  │     模型名 + sp 空(未配置或当前不可解析) → +gen 自动套 modality 兜底默认(video 720p/5s, image 2048)
  │     EP(ep-xxx)            → 跳过, 不强填(背后能力未知), 服务端裁决
  │
  ▼ Step 3 据可用参数生成  ──► arkcli +gen --model $MODEL [Step2 允许的参数] "prompt"
  │
  ▼ Step 4【结果处理】
        视频 = 异步：返回 task_id + status=queued(**不是失败!**) → arkcli gen get <task_id> 轮询;轮到 succeeded 自动下载到本地(local_path);要同步阻塞加 --wait
        图片 = 同步：直接返回 output_url + local_path

Step 1【强制】解析显式 Endpoint，或列出 profile 可用资源

用户已经显式给出 Endpoint 时，不要先用 active profile 的模型池覆盖它：

arkcli resources resolve "$ENDPOINT" --format json

• 读取 generation_modality 决定 image/video；image_or_video 或 unknown 时再结合 用户意图，必要时显式补 --modality。
• 读取 resource_region；Endpoint + 显式 API Key 且未给 Base URL 时，CLI 用该 region 派生 platform Base URL。
• 不按 Endpoint ID 或绑定模型名称里的 seedream / seedance 子串猜模态。
• 显式 Endpoint + API Key 是临时调用，不切换 active profile，也不把值写回。

用户未给显式 Endpoint 时，再按 profile 列资源：

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

• 平台差异（resources list 已自动按 profile 分流，你只管读 items）：
  • platform profile → items 是推理接入点 EP（ep-xxx），每个 EP 内部绑定一个模型
  • agent-plan profile → items 是视觉模型名（如 doubao-seedance-2.0-fast）
  • coding-plan profile → 自身不含视觉模型，+gen image/video 会自动借道 platform 数据面，--model 必须显式传一个 platform 上的 EP
• is_default: true 标记的是该模态当前默认；用户没指定时优先用它
• 选定一个 id，记为 $MODEL，贯穿 Step 2/3
• 用户已明确给了模型/EP 时，仍建议 resources list 核对它在当前 profile 可用；若与默认不同，按 ../arkcli-shared/references/profile-defaults.md "Default 漂移检测与 promote nudge" 处理

Step 2【强制·EP 除外】查 $MODEL 的可用参数

arkcli models get "$MODEL" --transform supported_params

• $MODEL 是模型名：拿到该模型的 supported_params 清单（每项含 name / type / support / min / max / enum / required）。

  • MUST：Step 3 只能使用这里 support=true 的参数，且取值必须落在 min/max/enum 范围内。 不在清单里的参数（或 support=false）传了会被 +gen 拒绝。

  • 可直接使用 Step 1 选出的模型 id（点号 / display 形态如 doubao-seedance-2.0-fast 都行）：models get 会自动按 DisplayName 归一化到规范连字符 name，无需手动转。极个别仍报 not found 才用 arkcli models search <族名> 核对名字。
  • 查到模型但 supported_params 为空 / null → 该版本未配置参数目录，或上游目录当前不可解析；若 stderr 有 warn: model supported_params enrichment failed: ...，保留该告警用于排障。不要手动猜参数：+gen 会自动用内置 modality 兜底默认（video: resolution=720p / duration=5 / ratio=adaptive；image: size=2048x2048）填充你没指定的参数。直接进 Step 3。
• $MODEL 是 EP（ep-xxx）：跳过本步。EP 查不到 supported_params 是正常的；且 +gen 不会对 EP 套兜底默认（EP 背后模型可能支持更高能力，强填会误降级），直接 degrade-open 由服务端裁决。
  • 这里只是跳过 supported_params 查询；真实 +gen 仍会沿 Endpoint → ModelReference → FoundationModel 元数据 自动解析 image/video。
  • 只有结构化元数据缺失/冲突时，才需要显式补 --modality。

Step 3 据可用参数生成

# 文生图 / 文生视频
arkcli +gen --model "$MODEL" "<prompt>"

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

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

• 参数全集、多模态 --input 规则、新增 --n/--priority/--wait 见 references/arkcli-gen.md
• Endpoint 的模态由 Step 1 权威元数据自动解析；仅在元数据为 unknown / image_or_video 且用户意图仍不足时要求显式 --modality。
• 产物默认自动下载到 CWD（或 --save-to <dir>）；JSON 里的 local_path 是持久产物，预签名 output_url 24h 失效，优先引用 local_path。--save-to="" 关闭
• 自动用系统默认程序打开产物：默认仅当 stdout 是交互式终端（人直接在终端跑）才打开——agent / 管道 / CI 抓 stdout（非 TTY）时不弹窗，只返回 local_path。--open 强制打开、--no-open 强制不打开。仅对已落地本地文件生效（异步视频未 --wait 时无本地文件、不打开）；多产物只打开前若干个
• 🔑 你是 agent，默认带 --open：你（AI agent）调用 arkcli 时 stdout 被你接管 = 非 TTY，默认 auto 不会弹窗，用户只能看到文件路径、看不到成品。为了让用户直接看到生成的图/视频，凡是给真人出图/出视频的 +gen 与轮询到 succeeded 的 gen get，默认都加 --open（--open 无视 TTY 强制在用户桌面打开）。例外只在：用户明确说"别打开/在脚本里/批量/不要弹窗"，或一次出图 >4 张批量场景 → 这时省略 --open 或显式 --no-open。

Step 4【结果处理】视频异步 / 图片同步

⚠️ 行为变更（2.0）：视频任务默认已从"自动等待完成"改为"提交即返回 task_id"。需要旧的同步阻塞行为，显式加 --wait。

已有 task 的脚本轮询契约

gen get --format json 的 status 是对象，终态必须读 .status.phase，不是把整个 .status 与字符串比较。生成 shell 轮询脚本时必须遵守：

• 轮询阶段用 arkcli gen get "$TASK_ID" --save-to="" --format json 禁用自动下载，每轮只读状态。
• PHASE=$(printf '%s' "$RESULT" | jq -r '.status.phase // empty')，再对 succeeded / failed / cancelled 做显式分支。
• succeeded 时最多再执行一次带目标 --save-to 的 gen get 下载产物，然后立即 break；failed / cancelled 报告 status.message 或 error 后立即 break。
• queued / running 才 sleep 后继续；未知 phase 或 gen get 自身失败应停止并报错，不能当作 running 无限循环。
• 整个脚本只查已有 task，禁止在轮询或失败分支重新执行 +gen。

快速决策

• 用户要一步到位出图/视频 → 走本工作流（Step 1→2→3）
• 用户还没定模型 → Step 1 resources list 列当前 profile 候选；模型族不确定 → 转 ../arkcli-models/SKILL.md
• 图生图 / 参考素材 → Step 3 加 --input @<file>（可重复）
• 视频生成后"没看到视频" → 多半是异步 queued，用 arkcli gen get <task_id> --open 轮询；轮到 succeeded 那次会自动下载到本地（看返回的 local_path）并弹出成品，别重提
• 给真人出图/视频默认加 --open → 你是 agent（非 TTY），不加用户只能看到路径、看不到成品；只有"别打开/脚本里/批量 >4 张"才省略或 --no-open

进阶 flag 自然语言触发词表

命令一览

常见降级

• 模型名报 not found → models get 已自动归一化点号/display 形态，仍报多半是名字真写错了，用 arkcli models search <族名> 核对
• 参数被拒（param_not_supported）→ 回到 Step 2 看 supported_params，只用列出的；确需强制可加 +gen --force 跳过校验（服务端仍有最终裁决）
• 内容被审核拦截（ContentRiskBlocked / *SensitiveContentDetected / 命中敏感 / 版权）→ 不是参数问题、--force 也绕不过；调整 prompt / 输入素材里的敏感内容后重试。要结构化的拦截原因 + 修复指引，转 ../arkcli-doctor/SKILL.md 的 arkcli doctor error <code>（生视频拦截 5 个 subtype 全覆盖）
• 鉴权错误 → 转 ../arkcli-auth/SKILL.md

参考

• arkcli-shared — 认证和全局参数（必读）
• arkcli-models — Step 2 模型查询/supported_params 详解
• references/arkcli-gen.md — +gen 全参数 + 多模态 + 异步语义