# 对话与生成

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

- 开放式对话走 `+chat`，明确产出形态的理解任务走 `+understand`，生成任务走 `+gen`；
- `chat` / `gen` 是数据面产物的事后管理域（`get` / `list` / `delete`），本身不发起新的调用；
- 三条工作流都支持临时 API Key / Base URL / Endpoint 免配置执行，脚本与 CI 场景可复现。

<span id="chat-command"></span>
## +chat

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

```Bash
arkcli +chat <prompt>
```

示例：

```Bash
arkcli +chat "用三句话介绍你自己"
```

| 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 的心跳 |

<span id="gen-command"></span>
## +gen

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

```Bash
arkcli +gen <prompt>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--model` | string | 生成模型名称或 Endpoint ID（省略时取当前 profile 的 Resources.<modality>.Default） |
| `--modality` | string | 显式指定生成模态：image \| video（--model 传 Endpoint ID 时必填；--model 也省略时默认 image） |
| `--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 <task-id>' 异步轮询） |
| `--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 默认行为）。 |

<span id="understand-command"></span>
## +understand

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

```Bash
arkcli +understand <sub-skill|prompt> [prompt]
```

| 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） |

<span id="domain-chat"></span>
## chat

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

- 数据面产物：记录由 `+chat` 等 Responses API 调用产生，本域负责事后查询与清理；
- 只读为主，删除操作有确认闸门。

<span id="chat-delete-command"></span>
### chat delete

按 ID 删除已保存的响应

```Bash
arkcli chat delete <response-id>
```

<span id="chat-get-command"></span>
### chat get

按 ID 获取已保存的响应

```Bash
arkcli chat get <response-id>
```

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

<span id="chat-list-input-items-command"></span>
### chat list-input-items

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

```Bash
arkcli chat list-input-items <response-id>
```

| 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'`，直接去掉该参数即可 |

<span id="domain-gen"></span>
## gen

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

- 任务由 `+gen` 工作流产生，本域负责事后查询、取回与清理；
- 视频任务异步执行，轮询状态直到出图/出片完成。

<span id="gen-delete-command"></span>
### gen delete

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

```Bash
arkcli gen delete <task-id>
```

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

<span id="gen-get-command"></span>
### gen get

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

```Bash
arkcli gen get <task-id>
```

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

<span id="gen-list-command"></span>
### gen list

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

```Bash
arkcli gen list
```

| 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 过滤；多个可重复传 |