数据面工作流与它们的记录管理：对话、生成、多模态理解三条 + 工作流，以及对应会话/任务记录的事后查询。

开放式对话走 +chat，明确产出形态的理解任务走 +understand，生成任务走 +gen；

chat / gen 是数据面产物的事后管理域（get / list / delete），本身不发起新的调用；

三条工作流都支持临时 API Key / Base URL / Endpoint 免配置执行，脚本与 CI 场景可复现。

+chat

通过 Responses API 实现多模态对话、多轮对话、流式输出，支持临时 API Key、Base Url、Endpoint 免配置执行。

示例：

Flag	类型	说明
--model	string	模型名称或 Endpoint ID。不传时，默认使用当前 Profile 中的文本模型默认资源。
--input	string_slice	输入素材引用，例如 @photo.jpg。传入多个文件时，可重复使用该参数。
--stream	bool	开启流式输出。
--previous-response-id	string	基于上一轮响应 ID 继续对话。
--instructions	string	在提示词前追加系统级指令。
--temperature	string	设置采样温度，例如 0.7。
--top-p	string	设置核采样参数 top_p，例如 0.9。
--max-output-tokens	int	设置模型回复的最大输出 token 数。
--store	bool	保存本次响应，以便后续通过 --previous-response-id 继续对话。
--reasoning-effort	string	推理深度：minimal \| low \| medium \| high
--tools	string_slice	按类型快速指定工具，例如 --tools web_search；多个可重复。function 工具请用 --tools-file。
--tools-file	string	存放 tools 数组的 JSON 文件路径（完整 SDK 结构）。在 --tools 条目之后合并。
--tool-choice	string	工具调用策略：auto \| required \| none
--max-tool-calls	int	每轮最多允许的工具调用次数
--caching	string	服务端提示词缓存：enabled \| disabled
--cache-prefix	bool	开启 prefix-cache 模式（仅在 --caching 开启时有意义）
--thinking	string	内部推理：auto \| enabled \| disabled
--expire-at	int	已保存响应的回收时间戳（epoch 秒；仅在 --store 时有意义）
--include-events	bool	仅流式模式：把每个 SDK 事件以一行 NDJSON 输出到 stdout，替代人类可读文本
--text-format	string	输出格式：text \| json_object \| json_schema
--text-schema	string	JSON Schema 文件路径（--text-format=json_schema 时必填）
--text-schema-name	string	附加到 JSON schema 的名称（默认：arkcli_response）
--text-strict	bool	强制严格遵循 schema（仅在 --text-format=json_schema 时有效）
--no-progress	bool	关闭非流式调用期间周期性打印到 stderr 的心跳

+gen

根据提示词生成素材（图片直接内联返回；视频立即返回任务 ID，加 --wait 可阻塞到视频生成完成；--modality audio 支持语音合成 TTS）

Flag	类型	说明
--model	string	生成模型名称或 Endpoint ID（省略时取当前 profile 的 Resources..Default）
--modality	string	显式指定生成模态：image \| video \| audio（--model 传 Endpoint ID 时必填；--model 也省略时默认 image；audio 见下方语音合成说明）
--input	string_slice	引用素材；多个可重复传入。可用 @ 前缀的本地路径，或 http(s)/file/tos URL。可选角色前缀 first:/last:/ref:/none:
--name	string	可选的任务名覆盖
--version	string	模型版本覆盖
--size	string	图片输出尺寸
--image-count	int	生成图片数量（图片任务；大于 1 会启用顺序自动生成）
--n	int	--image-count 的别名（图片任务）；两者同时设置时以本参数为准
--resolution	string	素材分辨率
--duration	int	视频时长（秒）
--frames	int	视频帧数（在支持的模型上会覆盖 duration）
--seed	int	确定性生成的随机种子
--watermark	bool	是否添加水印
--generate-audio	bool	是否生成同步音频
--guidance-scale	string	无分类器引导系数（图片任务；浮点数，例如 7.5）
--optimize-prompt	bool	是否启用服务端提示词优化（图片任务）
--output-format	string	图片输出格式：jpeg \| png
--response-format	string	图片响应格式：url \| b64_json（图片任务；服务端默认 url）
--prompt-thinking	string	提示词优化思考模式：auto \| enabled \| disabled（图片任务；仅在设置 --optimize-prompt 时生效）
--prompt-mode	string	提示词优化模式：standard \| fast（图片任务）
--sequential	string	顺序生成图片：auto \| disabled。留空则保持 arkcli 的自动 auto 模式（--image-count > 1 时）；传 disabled 可强制单图生成，即使 --image-count > 1
--ratio	string	覆盖输出宽高比，如 16:9 / 9:16 / 1:1（视频任务）
--camera-fixed	bool	锁定虚拟相机（视频任务）
--return-last-frame	bool	在返回最终视频的同时返回最后一帧 URL（视频任务）
--draft	bool	草稿模式：更快更便宜，质量更低（视频任务）
--service-tier	string	服务等级覆盖（视频任务）
--safety-id	string	调用方提供的安全标识（视频任务）
--execution-expires-after	int	服务端任务存活时间（秒，视频任务）
--priority	int	调度优先级 0-9，越大越早（视频任务；受各模型 supported_params 限制）
--callback-url	string	接收任务生命周期事件 POST 的 URL（视频任务；created/running/succeeded/failed）
--wait	bool	阻塞直到视频任务结束再返回（视频任务；默认 false——立即提交并返回 task id，之后用 'arkcli gen get' 异步轮询）
--extra-body	string	前向兼容的 JSON 对象，其键会合并进顶层请求体，例如 --extra-body '{"new_field":"value"}'（视频任务）
--tools	string_slice	启用工具；目前支持 web_search。可重复。
--stream	bool	以 NDJSON 流式输出图片生成帧（仅图片任务）；每行是一个 image_generation.* 事件 JSON
--save-to	string	本地保存生成素材的目录（默认：当前目录；传 --save-to="" 关闭）（默认 .）
--force	bool	跳过逐模型的 supported_params 校验，按原样提交（模型目录过期时的逃生口）
--open	bool	下载完成后用系统默认应用打开生成的素材。默认 auto：仅当 stdout 是交互终端（人手动执行）时打开，agent/管道/CI 下保持安静。传 --open 强制开启，--no-open 强制关闭。
--no-open	bool	即使在交互终端下也不自动打开生成的素材（覆盖 auto/--open 默认行为）。

语音合成（--modality audio）专用参数，仅火山 Agent Plan 个人版/企业版支持；传给图片/视频会报错：

Flag	类型	说明
--speaker	string	音色（默认 zh_female_vv_uranus_bigtts）
--audio-protocol	string	音频协议：http（默认）\| websocket 单向/双向流式
--text-stream	bool	双向 WS 下从 stdin 增量发送文本
--sample-rate	string	采样率（默认 24000）
--speech-rate	int	语速（百分比）
--loudness-rate	int	响度（百分比）
--emotion	string	情感标签
--emotion-scale	string	情感强度
--additions	string	附加参数 JSON（如 '{"context_texts":["用平静温柔的语气朗读"]}'）
--bit-rate	int	比特率
--enable-subtitle	bool	同时生成字幕
--subtitle-format	string	字幕格式（默认 srt）

| --no-gallery | bool | 不把生成的图片复制归档进本地 gallery（也可用环境变量 ARKCLI_NO_GALLERY 控制） |

+understand

多模态理解（图片 / 文档 / 视频）：由 Responses API 上的子技能实现；省略子技能时按 --input 的模态自动路由

Flag	类型	说明
--input	string_slice	输入素材，例如 @photo.jpg；可重复传入。本地图片 / 视频 / 文档会自动上传。
--model	string	覆盖子技能默认模型（名称或 Endpoint ID）
--stream	bool	增量流式输出响应
--system-prompt-override	string	完全替换子技能内置的 system 提示词
--system-prompt-append	string	在子技能内置 system 提示词之后追加额外指令
--temperature	string	采样温度（浮点数，如 0.7）
--top-p	string	核采样 top_p（浮点数，如 0.9）
--max-output-tokens	int	回复的最大输出 Token 数
--reasoning-effort	string	推理深度：minimal \| low \| medium \| high
--thinking	string	内部推理：auto \| enabled \| disabled
--store	bool	持久化该响应，便于之后取回
--no-progress	bool	关闭非流式调用期间周期性打印到 stderr 的心跳
--timeout	string	本地文件准备与推理的最长耗时（例如 2m 或 10m）

chat

对话会话记录管理：chat get 查看历史会话、chat delete 删除、chat list-input-items 列出会话输入项。

数据面产物：记录由 +chat 等 Responses API 调用产生，本域负责事后查询与清理；

只读为主，删除操作有确认闸门。

chat delete

按 ID 删除已保存的响应

chat get

按 ID 获取已保存的响应

Flag	类型	说明
--include	string_slice	include 提示（image_url\|audio_url\|encrypted_content）；多个可重复传入。注意：SDK 与后端版本可能不一致——当前线上在某些账号下不接受任何文档中的取值；若遇到 Invalid value for 'include'，直接去掉该参数即可

chat list-input-items

分页列出某个已保存响应的输入项

Flag	类型	说明
--after	string	游标：列出该条目 ID 之后的数据
--before	string	游标：列出该条目 ID 之前的数据
--limit	int	分页大小（1-100，服务端默认 20）
--order	string	排序方向：asc \| desc（服务端默认 desc）
--include	string_slice	include 提示（image_url\|audio_url\|encrypted_content）；多个可重复传入。注意：SDK 与后端版本可能不一致——当前线上在某些账号下不接受任何文档中的取值；若遇到 Invalid value for 'include'，直接去掉该参数即可

gen

生成任务记录管理：gen get 查询任务详情与结果、gen list 列出历史任务、gen delete 删除记录。

任务由 +gen 工作流产生，本域负责事后查询、取回与清理；

视频任务异步执行，轮询状态直到出图/出片完成。

gen delete

按 ID 删除异步内容生成任务（非交互场景必须用 --yes 确认）

Flag	类型	说明
--yes	bool	跳过交互确认（适合内联执行）

gen get

按 ID 获取异步内容生成任务（任务成功后自动下载素材）

Flag	类型	说明
--save-to	string	任务成功后本地保存素材的目录（默认：当前目录；传 --save-to="" 关闭）（默认 .）
--open	bool	用系统默认应用打开下载的素材。默认 auto：仅在交互终端下打开，agent/管道/CI 下保持安静。传 --open 强制开启，--no-open 强制关闭。
--no-open	bool	即使在交互终端下也不自动打开下载的素材（覆盖 auto/--open 默认行为）。

gen list

分页列出异步内容生成任务（视频 / 3D / 后续模态）

Flag	类型	说明
--page-num	int	页码，从 1 开始；省略时使用服务端默认值
--page-size	int	每页条数；省略时使用服务端默认值
--status	string	按任务状态过滤：succeeded \| failed \| running \| queued \| cancelled
--model	string	按模型名称或 Endpoint ID 过滤
--service-tier	string	按服务等级覆盖项过滤
--task-id	string_slice	按任务 ID 过滤；多个可重复传

gen gallery

本地 gallery 管理：+gen 生成的图片会自动归档到产品状态目录的 gallery；本命令只操作本地状态，不访问控制面。

Flag	类型	说明
--older-than	duration	只清理早于该时长的文件（如 168h），与 --all 二选一
--all	bool	删除 gallery 内全部普通文件；必须与 --older-than 二选一
--yes	bool	跳过交互确认

火山方舟