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。
为什么是工作流(核心,先理解再执行)
用户说"生成一个视频/一张图",本质是三件独立的事,必须按序:
① 当前 profile 能用哪些模型 ── 不同 profile 模型来源完全不同(EP vs 模型名)
② 该模型支持哪些参数 ── 不查就传参 = 瞎猜 = 被校验拒/被后端拒
③ 按可用参数真去生成
把这三步压成"直接 +gen 猜一条命令",正是失败之源:模型名形态不对会 404,参数模型不支持会被拒。
适用场景
- "生成一张图" / "文生图" / "画一个 X"
- "生成一个视频" / "文生视频"
- 图生图 / image-edit / 加参考图;图生视频(I2V);参考视频(R2V);参考音频
- "用这张图当首帧生成视频" / "保持这个参考视频的运动"
工作流总览
用户意图: "生成 X"
│
▼ Step 1【强制】列当前 profile 可用模型 ──► arkcli resources list --modality image|video
│ 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 空(没配,如 2.0/1.5-pro) → +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【强制】列出当前 profile 可用的模型
# 按目标模态列;输出 items[].id 就是可作 --model 的候选
arkcli resources list --modality video # 或 image
- 平台差异(resources list 已自动按 profile 分流,你只管读 items):
platformprofile → items 是推理接入点 EP(ep-xxx),每个 EP 内部绑定一个模型agent-planprofile → items 是视觉模型名(如doubao-seedance-2.0-fast)coding-planprofile → 自身不含视觉模型,+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
resources list给的 id(点号 / display 形态如doubao-seedance-2.0-fast都行):models get会自动按 DisplayName 归一化到规范连字符 name,无需手动转。极个别仍报not found才用arkcli models search <族名>核对名字。 - 查到模型但
supported_params为空 /null(很多模型没配,如doubao-seedance-2-0/doubao-seedance-1-5-pro)→ 不用手动补参数:+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 由服务端裁决。
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 - 产物默认自动下载到 CWD(或
--save-to <dir>);JSON 里的local_path是持久产物,预签名output_url24h 失效,优先引用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【结果处理】视频异步 / 图片同步
| 模态 | 默认行为 | 你该怎么读结果 |
|---|---|---|
| 视频 | 异步:立即返回 task_id + status: queued |
queued 不是失败。用 arkcli gen get <task_id> --open 轮询到 succeeded——这次 gen get 会顺手把产物下载到本地并回带 local_path(默认 CWD,<task-id>.mp4),--open 让成品直接在用户桌面弹出(你是 agent,非 TTY,不加就只有路径);不必再手动 curl output_url;不要因为没拿到视频就重提 +gen(会建新任务) |
视频 + --wait |
同步:阻塞到完成再返回 | arkcli +gen ... --wait --open,直接拿 output_url / local_path 并弹出成品 |
| 图片 | 同步:直接返回 output_url + local_path |
arkcli +gen ... --open 让图片直接弹给用户看 |
⚠️ 行为变更(2.0):视频任务默认已从"自动等待完成"改为"提交即返回 task_id"。需要旧的同步阻塞行为,显式加
--wait。
快速决策
- 用户要一步到位出图/视频 → 走本工作流(Step 1→2→3)
- 用户还没定模型 → Step 1
resources list列候选;模型族不确定 → 转../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 自然语言触发词表
| 用户怎么说 | 对应 flag / 命令 |
|---|---|
| "生成完直接打开/帮我打开看看/出来就弹给我" | arkcli +gen --open(强制用系统默认程序打开;默认在交互终端已自动打开) |
| "别自动打开/不要弹窗/我在脚本里跑别开" | arkcli +gen --no-open(强制不打开) |
| "预览/别真发/只看参数/dry run/试跑/先看一下" | arkcli +gen --dry-run(不会真正生成) |
| "强制执行/跳过校验/我知道不支持但想试一下" | arkcli +gen --force |
| "连贯多张/按顺序/统一风格/4格漫画/连续图片" | arkcli +gen --sequential |
| "我之前的任务/生成历史/任务列表/任务状态" | arkcli gen list(列出所有异步生成任务) |
| "那个任务跑完没/查进度/查状态" | arkcli gen get <task_id> |
命令一览
| 命令 | 角色 |
|---|---|
arkcli resources list --modality image|video |
Step 1 — 当前 profile 可用模型/EP |
arkcli models get <model> --transform supported_params |
Step 2 — 查模型可用参数 |
arkcli +gen |
Step 3 — 按可用参数生成 |
arkcli +gen --stream |
图片任务流式 NDJSON 输出 |
arkcli gen get <task-id> |
Step 4 — 轮询/查询异步视频任务 |
arkcli gen list |
列出/过滤异步生成任务 |
arkcli gen delete <task-id> |
删除异步生成任务 |
常见降级
- 模型名报
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全参数 + 多模态 + 异步语义