CLI 工具 - 千问AI平台

版本 1.6.0

千问AI平台 CLI 已开源，欢迎查看源码、提交 Issue 或参与贡献：GitHub

快速开始

需要 Node.js 18 或更高版本。npm 包名及可安装版本以实际发布页为准。

安装并验证：

npm install -g @qianwenai/qianwen-cli
qianwen version

更新到最新版本（已安装用户）：

npm 用户直接运行以下命令即可更新到最新版：

npm install -g @qianwenai/qianwen-cli@latest

也可运行以下命令检查是否有新版本：

qianwen version --check
qianwen update

update 只检查并提示，不会自动安装，运行后按它输出的命令执行即可。刚完成第 1 步即为最新，可跳过本步。

交互式登录：

qianwen auth login

执行第一条查询：

qianwen models list

发起首次模型调用：

qianwen chat create "用一句话介绍千问AI平台"

不带参数运行 qianwen 进入交互模式；带命令运行时执行一次后退出。无需预设环境变量；登录流程会保存管理凭证。models list 返回结果即表示安装、网络与登录均可用。Agent 可运行 qianwen config set output.format json 固定 JSON 输出；验证失败时运行 qianwen doctor --format json。

模型与文档

想筛选可用模型、核对模型详情，或从官方文档找到接入说明？从这里开始。

models list

列出可用模型，并按输入、输出模态筛选。

qianwen models list [--input <text|image|video|audio|vector>] [--output <text|image|video|audio|vector>] [--page <integer>] [--per-page <integer>] [--all] [--verbose] [--format <auto|table|json|text>]

qianwen models list --input image --output text
qianwen models list --all --verbose --format json

Flag	类型	必填	默认	说明
`--input <modality>`	枚举	否	未设置	输入模态：text、image、video、audio、vector
`--output <modality>`	枚举	否	未设置	输出模态：text、image、video、audio、vector
`--page <integer>`	整数	否	1	页码；非数字或小于 1 时回退 1
`--per-page <integer>`	整数	否	20	每页模型数；非数字或 0 回退 20，负数归一为 1
`--all`	布尔	否	false	返回全部模型并关闭分页；强制 JSON
`--verbose`	布尔	否	false	补充详情字段；强制 JSON

JSON 输出结构示例（示例值仅用于说明字段）：

{
  "models": [
    {
      "id": "qwen3.6-plus",
      "modality": {
        "input": ["text", "image"],
        "output": ["text"]
      },
      "can_try": true,
      "free_tier": {
        "mode": "standard",
        "quota": {
          "remaining": 850000,
          "total": 1000000,
          "unit": "tokens",
          "used_pct": 15,
          "status": "valid",
          "resetDate": "2026-08-01T00:00:00.000Z"
        }
      },
      "pricing": {
        "tiers": [
          {
            "label": "输入<=256k",
            "input": 1.6,
            "output": 6.4,
            "cache_creation": 2,
            "cache_read": 0.16,
            "unit": "CNY/1M tokens"
          },
          {
            "label": "256k<输入<=1m",
            "input": 4.8,
            "output": 19.2,
            "cache_creation": 6,
            "cache_read": 0.48,
            "unit": "CNY/1M tokens"
          }
        ],
        "summary": {
          "cheapest_input": 1.6,
          "cheapest_output": 6.4,
          "unit": "CNY/1M tokens",
          "billing_type": "token"
        }
      },
      "features": ["function-calling"],
      "context": {
        "context_window": 131072,
        "max_input": 122880,
        "max_output": 8192
      }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

示例为默认（非 --verbose）分页场景：features、context 在列表接口返回时即出现，--verbose 另增 description、tags、rate_limits、metadata；free_tier 恒为对象，无免费额度时其 mode/quota 为 null；--all 时顶层以 all: true 替代分页字段。找到候选模型后，运行 qianwen models info <id> 查看完整定价、上下文和限流信息。该命令返回模型元数据，不提供完整参数 Schema；调用参数及取值应以对应模型的官方 API 参数页为准。

models info

查看一个模型的完整详情；位置参数和 --model 至少提供一个。

qianwen models info [id] [--model [id]] [--format <auto|table|json|text>]

qianwen models info qwen3.6-plus
qianwen models info --model qwen3.6-plus --format json

Flag / 参数	类型	必填	默认	说明
`[id]`	字符串	条件必填	无	模型 ID
`--model [id]`	字符串	条件必填	无	模型 ID；与位置参数二选一

需要继续比较候选模型时，运行 qianwen models search <query> 缩小范围。也可运行 qianwen docs search <model-id> 辅助查找参数页，但需核对结果中的模型 ID 和接口类型。

models search

按关键词或模态搜索模型。

qianwen models search <query> [--page <integer>] [--per-page <integer>] [--all] [--format <auto|table|json|text>]

qianwen models search "function calling"
qianwen models search image --all --format json

Flag / 参数	类型	必填	默认	说明
`<query>`	字符串	是	无	搜索词
`--page <integer>`	整数	否	1	页码
`--per-page <integer>`	整数	否	20	每页模型数
`--all`	布尔	否	false	返回全部匹配项；强制 JSON

docs search

无需登录即可搜索官方文档，也可直接查看当前结果中的第 N 条。

qianwen docs search <query> [--limit <integer>] [--page <integer>] [--language <en|zh>] [--view <integer>] [--format <auto|table|json|text>]

qianwen docs search "chat completions" --language zh --limit 10
qianwen docs search "API Key" --view 1

Flag / 参数	类型	必填	默认	说明
`<query>`	字符串	是	无	搜索词
`--limit <integer>`	整数	否	20	JSON/text 每页 1-100 条；table 模式最多 5 条
`--page <integer>`	整数	否	1	页码
`--language <lang>`	字符串	否	zh	文档语言；en 映射 en，zh 开头映射 zh，其他值静默回退 zh
`--view <integer>`	整数	否	未设置	查看当前结果中从 1 开始的序号

找到目标条目后，运行 qianwen docs view <path-or-url> 阅读正文。

docs view

按文档路径或 URL 查看页面内容。

qianwen docs view <path-or-url> [--format <auto|table|json|text>]

qianwen docs view /docs/api-reference/preparation/cli

参数	类型	必填	默认	说明
`<path-or-url>`	字符串	是	无	文档路径或 URL

认证、账号与空间

想登录、确认凭证是否有效，或检查账号能访问哪些空间？用这组命令。

模型调用要求有效的管理登录；显式传入 --api-key 不能跳过登录检查。通过检查后，推理凭证按 --api-key → QIANWEN_API_KEY → DASHSCOPE_API_KEY → 当前管理登录凭证的公开顺序选择。登录并保存凭证；交互式终端优先 PKCE，非交互环境使用 Device Flow。

qianwen auth login [--init-only] [--complete] [--timeout <seconds>] [--format <auto|table|json|text>]

qianwen auth login
qianwen auth login --init-only --format json
qianwen auth login --complete --timeout 180

Flag	类型	必填	默认	说明
`--init-only`	布尔	否	false	输出授权信息后立即退出
`--complete`	布尔	否	false	继续并完成待处理的登录会话
`--timeout <seconds>`	整数	否	120	`--complete` 的轮询超时秒数

非 TTY 且未指定 --init-only/--complete 时自动按 init-only 方式返回。凭证优先写入系统钥匙串，不可用时回退到加密文件。也可以直接运行 qianwen login。登录成功后，运行 qianwen auth status --format json 检查凭证，再运行 qianwen models list 验证查询权限。

auth status

检查本地凭证及服务端验证状态。

qianwen auth status [--format <auto|table|json|text>]

qianwen auth status --format json

完整 JSON 结构示例：

{
  "authenticated": true,
  "server_verified": true,
  "auth_mode": "device_flow",
  "source": "keychain",
  "user": {
    "aliyunId": "example-user"
  },
  "token": {
    "expires_at": "2026-08-01T00:00:00.000Z",
    "scopes": ["inference:read", "usage:read", "config:write"]
  }
}

服务端不可达但本地凭证仍有效时，server_verified 为 false，并可能带 warning。从 1.4.0 起，未登录或凭证过期也返回退出码 0；凭证过期时 JSON 还包含 reason: "token_expired"。

脚本迁移：不要再用 auth status 的退出码判断是否登录，请读取 JSON 中的 authenticated 字段。

若 authenticated 为 false，重新运行 qianwen auth login。

auth logout

注销并删除本地凭证。也可以直接运行 qianwen logout。

qianwen auth logout [--format <auto|table|json|text>]

qianwen auth logout

workspace list

列出当前账号可访问的空间。

qianwen workspace list [--format <auto|table|json|text>]

qianwen workspace list --format json

列出空间后，运行 qianwen workspace limit 判断账号是否还能新增空间。

workspace limit

查看已用空间数与账号硬上限。

qianwen workspace limit [--format <auto|table|json|text>]

qianwen workspace limit

模型调用

从终端发起对话、图像生成与编辑、视频生成、语音识别、语音合成、3D 和音乐调用，并查询异步任务。

需求	命令	主要执行方式与结果
文本或多媒体对话	`qianwen chat create`	交互终端默认流式，非交互输出默认非流式
生成或编辑图像	`qianwen image generate`	按模型 ID 选择同步或异步，成功图像默认写入本地
文生视频或图生视频	`qianwen video generate`	始终异步，默认等待；只有传入 `--out` 才下载结果
录音文件转写	`qianwen audio transcribe`	Qwen 模型同步，其他模型异步
文本转语音	`qianwen audio speech`	按模型选择 HTTP 或 WebSocket，音频默认写入本地
文本或单图生成 3D	`qianwen model3d generate`	始终异步，默认等待并下载模型文件和预览图
根据提示词生成音乐	`qianwen music generate`	默认通过上游 SSE 接收结果，完成后写入音频文件
查询异步任务	`qianwen task get`	单次查询，不持续轮询

八条命令都要求有效的管理登录；即使显式传入 --api-key，也不能跳过 qianwen auth login。通过检查后，推理凭证按 --api-key → QIANWEN_API_KEY → DASHSCOPE_API_KEY → 当前管理登录凭证的公开顺序选择。CLI 没有公开 --endpoint。不同模型支持的参数及取值不同。CLI 接受参数、发送字段、HTTP 2xx、退出 0 或获得 task id，都不代表模型已支持或实际采用该参数。本页只说明 CLI 入口；模型参数以各命令末尾链接的对应模态或模型 API 参数页为准。qianwen models info <id> 只返回模型元数据；qianwen docs search <model-id> 只是关键词检索辅助，结果需核对模型 ID 与接口类型。 --request 接受内联 JSON、@file 或从 stdin 读取的 -，根节点必须是对象。显式 --model 覆盖 request 中的 model；便捷 Flag 与 request 中同义字段并存时通常报 PARAM_LAYER_CONFLICT 并退出 4。@file 指请求 JSON 文件，不是待上传的媒体文件。

显式文件入口	按量付费	Token Plan	关键边界
Chat `--image` / `--video`	本地文件或 URL	仅目标模型支持且可访问的 URL	本地文件由 CLI 上传后改写为临时 `oss://`
Image `--image`	本地文件或 URL	仅目标模型支持且可访问的 URL	只有 CLI 识别的编辑模型才处理该入口
Video `--image`	本地文件或 URL	仅目标模型支持且可访问的 URL	该 Flag 把调用切换为 I2V
ASR `[file-or-url]`	本地文件或 URL	仅目标模型支持且可访问的 URL	位置参数是唯一显式文件入口
3D `--image`	本地文件或 URL	仅目标模型支持且可访问的 URL	仅支持单图入口，且不能与位置 prompt 并用

按量付费通过上述显式入口接收本地文件时，CLI 会先上传文件，再把输入改写为临时 oss:// 地址。HTTP/HTTPS 或 oss:// 会作为 URL 发送，但这不保证目标模型支持该输入，也不保证服务端能够访问。Token Plan 不支持 CLI 上传本地文件，应改用目标模型支持且可访问的 URL；触发客户端守卫时，错误为 LOCAL_UPLOAD_UNSUPPORTED、退出码 4，提示为“Token Plan 密钥（sk-sp-）只支持以 URL 形式传入媒体，无法上传本地文件。请将图片 / 视频 / 音频改为公网 URL（http/https 或 oss://），或改用按量付费密钥（sk- / sk-ws-）。” --request 中的本地路径只是 JSON 字符串，CLI 不会自动发现或上传，也不会触发上述 Token Plan 本地上传守卫。TTS、Music 和 task get 没有上传型输入；--out 始终是结果位置，不是上传入口。image generate、video generate、audio speech、model3d generate 和 music generate 显式传入 --out 时，会在登录检查和网络请求前创建缺失的目标目录并检查可写性；即使之后因未登录或请求失败退出，目录也可能已经创建。

chat create

发起一次文本或多媒体对话；当前默认模型为 qwen3.8-max。

qianwen chat create [prompt] [--model <id>] [--temperature <n>] [--max-tokens <n>] [--stream] [--thinking|--no-thinking] [--image <path-or-url>] [--video <path-or-url>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen chat create "用一句话解释无服务器计算"
qianwen chat create "描述这张图片" --image https://example.com/image.png
qianwen chat create "列出三个方案" --stream --format json

Flag / 参数	类型	必填	默认	说明
`[prompt]`	字符串	条件必填	无	文本提示词；与 `--request` 至少提供一项
`--model <id>`	字符串	否	`qwen3.8-max`	模型 ID；显式值覆盖 request 中的 `model`
`--temperature <n>`	数值	否	未设置	采样温度；CLI 只校验为有限数值
`--max-tokens <n>`	整数	否	未设置	总输出 token 预算；必须为正整数，发送为 `max_completion_tokens`
`--stream`	布尔	否	TTY 为 true；非 TTY 为 false	强制流式输出；当前没有 `--no-stream`
`--thinking` / `--no-thinking`	布尔	否	未设置	发送 `enable_thinking`；控制人读输出和流式事件是否显示思考内容
`--image <path-or-url>`	字符串	否	未设置	随位置 prompt 附加一张图片；可与 `--video` 同时使用
`--video <path-or-url>`	字符串	否	未设置	随位置 prompt 附加一个视频；可与 `--image` 同时使用
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与 prompt 至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用，不跳过管理登录
`--format <fmt>`	枚举	否	auto	auto、table、json、text

prompt 不能与 request.messages 并存。--image 和 --video 必须同时提供位置 prompt；纯 --request 调用中的媒体 Flag 不会写入请求。--temperature、--max-tokens、有效的流式设置、--thinking 或媒体 Flag 与 request 中对应字段并存时，报 PARAM_LAYER_CONFLICT 并退出 4。CLI 是否进入流式输出只由显式 --stream 或 stdout 是否为 TTY 决定，request.stream 不能切换 CLI 输出分支；TTY 的隐式流式设置也可能与 request.stream 冲突。非流式 --format json 返回 {meta,data}，并保留上游返回的 reasoning_content；--thinking 只控制人读输出和流式事件是否显示思考内容。流式 --format json 返回 NDJSON，不是单个 JSON 文档：正文事件各占一行并含一段增量 delta，应按顺序拼接；启用 --thinking 后，思考增量行还带 reasoning: true。只有成功结束时，最后一行才是独立的 meta 记录，可包含 request_id、model、finish_reason 和 token 用量，缺失字段不会补空值。流事件失败时错误写入 stderr 并退出 1；初始网络失败通常退出 3。失败前 stdout 可能已有部分 delta，且不会出现 meta 尾行。--image 和 --video 使用本节开头的文件规则；Token Plan 传本地文件时报 LOCAL_UPLOAD_UNSUPPORTED 并退出 4。查看模型与参数，请访问文本生成模型和 OpenAI Chat API 参考。命令成功不代表每个参数已被模型采用。

image generate

生成图像，或使用 CLI 识别的编辑模型处理一张参考图；当前默认模型为 qwen-image-3.0-pro。

qianwen image generate [prompt] [--model <id>] [--size <width*height>] [--n <count>] [--image <path-or-url>] [--out <path>] [--response-format <fmt>] [--request <json|@file|->] [--no-wait] [--timeout <seconds>] [--api-key <key>] [--format <auto|table|json|text>]

qianwen image generate "剪纸风格的云端城市"
qianwen image generate "把天空替换为晚霞" --model qwen-image-edit-plus --image ./photo.png
qianwen image generate "水彩狐狸" --model wanx2.1-t2i-turbo --no-wait --format json

Flag / 参数	类型	必填	默认	说明
`[prompt]`	字符串	条件必填	无	生成或编辑提示词；与 `--request` 至少提供一项
`--model <id>`	字符串	否	`qwen-image-3.0-pro`	模型 ID
`--size <width*height>`	字符串	否	未设置	输出尺寸；CLI 只校验 `数字*数字` 形式
`--n <count>`	整数	否	未设置	生成数量；必须为正整数，并受 CLI 按模型 ID 判断的 1 或 6 张上限限制
`--image <path-or-url>`	字符串	否	未设置	随位置 prompt 提供编辑来源图像；要求显式选择 CLI 识别的编辑模型
`--out <path>`	字符串	否	当前目录	本次生成完成后写入的图像文件或目录位置
`--response-format <fmt>`	字符串	否	未设置	只有精确值 `b64` 生效；需配合 `--format json` 读取 base64
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与 prompt 至少提供一项
`--no-wait`	布尔	否	false	异步模型提交后立即返回 task id
`--timeout <seconds>`	数值	否	300	同步请求超时，或异步轮询截止阈值；必须为正数
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

CLI 仅按模型 ID 选择执行方式：以 wanx 开头，或匹配 wan2.<minor> 且 minor 小于 6 时走异步；Wan 2.6 及更高版本与其他模型不由该规则判为异步。当前默认模型走同步。编辑能力同样由客户端按模型 ID 判断；当前默认模型配合 --image 会被 CLI 拒绝。--n 的 1 或 6 张上限也是客户端判断，不代表模型实际支持相同数量。 prompt 不能与 request.input 并存。--image 必须同时提供位置 prompt；纯 --request 调用中的 --image 不会写入请求。--size、--n 或 --image 与 request 中对应字段并存时报 PARAM_LAYER_CONFLICT 并退出 4。同步模型直接等待结果；异步模型默认每 2 秒查询，最长等待 300 秒。--no-wait 只影响异步模型，立即返回 task id 并退出 0，且不会为后续查询保留 --out 或 base64 后处理设置；异步等待达到阈值时，当前实现输出未完成状态并退出 0。这只表示提交或查询成功，不表示任务已经完成，应运行 qianwen task get <task-id> 继续查询。成功图像默认下载到 --out 或当前目录。使用 --response-format b64 --format json 时，CLI 读取结果 URL 的字节并转为 base64，通过 data.images[].b64 返回，不写入图像文件；table/text 只显示提示或 URL。其他 --response-format 值当前不会报错，但仍按默认方式下载，不应依赖这一静默行为。异步任务 FAILED 退出 1；同步请求或下载的网络失败通常退出 3，写盘失败通常退出 1。 --image 使用本节开头的文件规则。Token Plan 传本地文件时报 LOCAL_UPLOAD_UNSUPPORTED 并退出 4。查看参数，请访问图像生成模型；Qwen 同步图像生成与当前默认模型匹配，编辑模型和 Wanx 异步模型应分别从模态入口进入对应参数页。

video generate

提交文生视频或图生视频任务。未传 --image 时的当前默认模型为 happyhorse-1.1-t2v；传入 --image 时为 happyhorse-1.1-i2v。

qianwen video generate [prompt] [--model <id>] [--image <path-or-url>] [--wait|--no-wait] [--timeout <seconds>] [--out <path>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen video generate "一架纸飞机飞过城市"
qianwen video generate "让猫跑起来" --image ./cat.png --out ./cat.mp4
qianwen video generate "海上日出" --no-wait --format json

Flag / 参数	类型	必填	默认	说明
`[prompt]`	字符串	条件必填	无	视频提示词；与 `--request` 至少提供一项
`--model <id>`	字符串	否	见下文	模型 ID；默认值只由显式 `--image` 是否存在决定
`--image <path-or-url>`	字符串	否	未设置	首帧图像；传入后使用 I2V 当前默认模型
`--wait` / `--no-wait`	布尔	否	wait	等待终态，或提交后立即返回 task id
`--timeout <seconds>`	数值	否	900	异步轮询截止阈值；必须为正数
`--out <path>`	字符串	否	未设置	本次等待成功后下载的文件或目录；未传时只返回 URL
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与 prompt 至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

该命令始终异步提交，默认每 2 秒查询，最长等待 900 秒。默认模型选择只检查显式 --image，不检查 --request 内的图片；原生 I2V request 应显式设置 model。显式 T2V 模型不能与 --image 并用；prompt 不能与 request.input 并存；--image 与 request 中的 input 冲突。这些参数错误退出 4。不同 Wan 版本的首帧字段由 CLI 按模型协议组装，CLI 发送成功不代表目标模型实际采用。 --no-wait 返回 task id 并退出 0，只证明任务已提交，且不会为后续查询保留 --out。等待达到 --timeout 阈值时，先输出最后一次任务状态，再退出 8；已发出的查询可能使实际耗时略高于该值。任务 FAILED 退出 1。任务成功后，只有本次调用等待到成功且显式传入 --out 才下载文件，否则返回 URL。 --image 使用本节开头的文件规则。Token Plan 传本地文件时报 LOCAL_UPLOAD_UNSUPPORTED 并退出 4。查看参数，请访问视频生成模型、HappyHorse 文生视频或 HappyHorse 图生视频。

audio transcribe

转写本地录音文件或音频 URL；当前默认模型为 qwen-audio-3.0-asr-flash。

qianwen audio transcribe [file-or-url] [--model <id>] [--language <hint>] [--wait|--no-wait] [--timeout <seconds>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen audio transcribe ./meeting.wav
qianwen audio transcribe https://example.com/meeting.mp3 --language zh
qianwen audio transcribe https://example.com/meeting.wav --model paraformer-v2 --no-wait --format json

Flag / 参数	类型	必填	默认	说明
`[file-or-url]`	字符串	条件必填	无	录音文件或 URL；与 `--request` 至少提供一项
`--model <id>`	字符串	否	`qwen-audio-3.0-asr-flash`	模型 ID
`--language <hint>`	字符串	否	未设置	语言提示；Qwen 模型写入 `parameters.asr_options.language`，其他模型写入 `parameters.language_hints[]`
`--wait` / `--no-wait`	布尔	否	wait	对异步模型等待终态或立即返回 task id；Qwen 同步分支忽略该选择
`--timeout <seconds>`	数值	否	300	必须为正数；只控制异步轮询，Qwen 同步分支校验后不采用该值
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与位置参数至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

模型 ID 以 qwen 开头时走同步多模态请求，使用 messages 音频输入；其他模型走异步转写任务，使用 file_urls 输入。Qwen 分支从显式音频来源或 request messages 中第一个 audio URL 的扩展名推断 parameters.format，无法识别时使用 wav。这是客户端组装行为，不是模型格式支持保证。位置参数不能与 request.input 并存；--language 不能与 request 中对应语言字段并存，这些参数错误退出 4。Qwen 同步分支中，--wait、--no-wait 不改变执行方式，--timeout 也不控制同步请求；同步传输使用内部 60 秒超时。异步模型默认每 2 秒查询，最长等待 300 秒。--no-wait 返回 task id 并退出 0；等待到时先输出任务状态，再退出 8。异步成功后，CLI 会尝试读取首个结果 JSON URL，在人读输出中展示最多 200 个字符的转写预览与完整结果 URL；读取或解析失败时退回 URL。命令不会把完整转写 JSON 保存到本地。位置参数使用本节开头的文件规则。Token Plan 传本地文件时报 LOCAL_UPLOAD_UNSUPPORTED 并退出 4。查看模型与参数，请访问语音识别模型；如需继续查询异步任务，使用 qianwen task get <task-id>。

audio speech

将文本合成为音频并写入本地；当前默认模型为 qwen-audio-3.0-tts-plus。

qianwen audio speech [text] [--model <id>] [--voice <name>] [--out <path>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen audio speech "欢迎使用千问AI平台"
qianwen audio speech "欢迎使用千问AI平台" --voice longanhuan_v3.6 --out ./welcome.mp3

Flag / 参数	类型	必填	默认	说明
`[text]`	字符串	条件必填	无	要合成的文本；与 `--request` 至少提供一项
`--model <id>`	字符串	否	`qwen-audio-3.0-tts-plus`	模型 ID
`--voice <name>`	字符串	否	按模型与输入方式决定	音色 ID 或名称；“位置 text + Qwen 模型”调用默认补 `longanhuan_v3.6`，纯 `--request` 不补
`--out <path>`	字符串	否	当前目录	音频文件或目录位置
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与 text 至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

命令同步执行，但国内站会按模型选择协议：以 sambert 开头的模型走 WebSocket out 模式，cosyvoice-v3.5 系列走 WebSocket duplex 模式；其他 CosyVoice 模型与名称包含 qwen-audio 的模型走语音合成 HTTP 接口；其他通过预检的非实时 TTS 模型走多模态 HTTP 接口。多模态 Chat 模型会被本地拒绝并提示改用 chat create；名称同时包含 -tts 与 -realtime 的仅实时 TTS 模型也会被拒绝。上述只是客户端分派规则，模型是否支持具体参数仍以参数页为准。位置 text 不能与 request.input 并存。--voice 与 request.input.voice 冲突；同一语义不要同时放在便捷 Flag 和 request 的其他字段中。WebSocket 分支会把统一请求中的 text、voice 与 parameters 重组为协议字段，默认补 text_type=PlainText 和 format=mp3，不会补 sample_rate；这不是 Chat 式 stdout 增量，CLI 收齐音频后才写文件并输出结果。自定义音色相关模型失败时，错误会提示传入已创建的复刻或设计音色 ID。 HTTP URL 结果会下载，WebSocket 二进制结果会直接写文件；未传 --out 时写入当前目录。HTTP 2xx 但响应中没有可下载的音频 URL 时，当前实现返回空 data 并退出 0，不代表音频已经生成。HTTP 请求使用内部 60 秒超时；WebSocket 使用约 60 秒的整体计时器。HTTP 请求或下载超时通常报 NETWORK_ERROR 并退出 3；国内 WebSocket 的超时、连接错误、提前关闭或空音频当前报 API_ERROR 并退出 1；写盘失败通常退出 1。本命令没有公开 timeout Flag，也没有上传型输入。查看模型与参数，请访问语音合成模型和非实时语音合成 HTTP API；选择默认模型的系统音色时可查看 Qwen-Audio-TTS 音色列表。

model3d generate

在千问AI平台 CLI 中根据文本或单张图片生成 3D 模型；当前默认模型为 Tripo/Tripo-P1.0。

qianwen model3d generate [prompt] [--model <id>] [--image <path-or-url>] [--texture-quality <standard|detailed>] [--wait|--no-wait] [--timeout <seconds>] [--out <path>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen model3d generate "一个低多边形风格的机器人"
qianwen model3d generate --image ./chair.png --texture-quality detailed --out ./chair.glb
qianwen model3d generate "一只陶瓷茶壶" --no-wait --format json

Flag / 参数	类型	必填	默认	说明
`[prompt]`	字符串	条件必填	无	文本提示词；prompt、`--image`、`--request` 至少提供一项，且与 `--image` 互斥
`--model <id>`	字符串	否	`Tripo/Tripo-P1.0`	模型 ID
`--image <path-or-url>`	字符串	条件必填	未设置	单张参考图；prompt、`--image`、`--request` 至少提供一项，且与 prompt 互斥
`--texture-quality <level>`	枚举	否	未设置	standard 或 detailed；发送为 `parameters.texture_quality`
`--wait` / `--no-wait`	布尔	否	wait	等待终态，或提交后立即返回 task id
`--timeout <seconds>`	数值	否	900	异步轮询截止阈值；必须为正数
`--out <path>`	字符串	否	当前目录	下载模型文件与预览图的文件或目录位置
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；prompt、`--image`、`--request` 至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

必须提供 prompt、--image 或 --request 之一；prompt 与 --image 不能同时使用，prompt 也不能与 request.input 并存。--image 与 request.input.image、--texture-quality 与 request.parameters.texture_quality 重复时，报 PARAM_LAYER_CONFLICT 并退出 4；request 的 input 含其他字段但没有 image 时，显式 --image 会用单图输入替换整个 input。CLI 只检查图片属于 URL、oss:// 或存在的本地文件，不校验扩展名、MIME、尺寸或模型是否真正接受。该命令始终异步提交，默认每 2 秒查询，最长等待 900 秒。--no-wait 返回 task id 并退出 0，不下载文件；等待到时先输出最后状态，再退出 8；任务 FAILED 退出 1。成功结果可包含 3D 模型文件和预览图，默认全部下载。未传 --out 时写入当前目录；给多文件结果传单一文件名时，第一个产物使用该名称，后续产物追加序号并使用各自扩展名。界面提示下载 URL 有效 2 小时、task id 可在 24 小时内继续查询。 --image 使用本节开头的文件规则。Token Plan 传本地文件时报 LOCAL_UPLOAD_UNSUPPORTED 并退出 4。查看参数，请访问 Tripo 3D 模型生成和 Tripo 3D 生成 API。

music generate

在千问AI平台 CLI 中根据提示词或原生请求生成音乐；当前默认模型为 fun-music-v1。

qianwen music generate [prompt] [--model <id>] [--out <path>] [--timeout <seconds>] [--no-stream] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qianwen music generate "轻快的电子乐，适合产品演示开场"
qianwen music generate "安静的钢琴纯音乐" --out ./intro.mp3
qianwen music generate --request @music-request.json --no-stream --format json

Flag / 参数	类型	必填	默认	说明
`[prompt]`	字符串	条件必填	无	音乐提示词；与 `--request` 至少提供一项
`--model <id>`	字符串	否	`fun-music-v1`	模型 ID
`--out <path>`	字符串	否	当前目录	音频文件或目录位置
`--timeout <seconds>`	数值	否	300	必须为正数；默认 SSE 下为空闲超时，`--no-stream` 下为整次请求上限
`--no-stream`	布尔	否	false	不使用上游 SSE，改为一次阻塞请求
`--request <json\|@file\|->`	字符串	条件必填	无	原生请求体；与 prompt 至少提供一项
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次推理调用
`--format <fmt>`	枚举	否	auto	auto、table、json、text

prompt 与 request.input 不能同时提供；--model 覆盖 request 中的 model。--request 可携带歌词等原生字段，但 CLI 保留并发送字段不代表模型支持或采用；@file 只是请求 JSON 文件，不会上传其中的本地路径。默认通过上游 SSE 接收结果，--no-stream 改为一次阻塞 HTTP 请求。SSE 是 CLI 与上游之间的协议，不是 Chat 式 stdout 增量：CLI 会收集事件，收到最终 URL 后下载，或把收到的 base64 音频片段合并后写成 MP3，再统一输出结果。默认 SSE 的 --timeout 是首包或相邻网络数据块的空闲阈值，每次收到数据后重置，因此总时长可能超过 300 秒；长时间无数据时报 NETWORK_ERROR、退出 3，并提示增大 --timeout 或更换模型。成功音频默认写入 --out 或当前目录。SSE 未收到 stop 且没有 URL 或音频片段时报 UPSTREAM_ERROR 并退出 1；已收到 stop 但仍无音频时，当前实现可能返回空 data 并退出 0。一次阻塞请求若收到 HTTP 2xx 却没有可下载的音频 URL，同样返回空 data 并退出 0；这些情况都不代表音乐已经生成。下载失败通常退出 3，写盘失败通常退出 1。本命令没有上传型输入。查看模型与参数，请访问音乐生成和 Fun-Music API 参考。

task get

对已有 task id 发起一次状态查询；该命令不会持续轮询。

qianwen task get <task-id> [--out <path>] [--api-key <key>] [--format <auto|table|json|text>]

qianwen task get TASK_ID
qianwen task get TASK_ID --out ./results/ --format json

Flag / 参数	类型	必填	默认	说明
`<task-id>`	字符串	是	无	要查询的异步任务 ID
`--out <path>`	字符串	否	当前目录	已识别媒体或 3D 产物的文件或目录位置
`--api-key <key>`	字符串	否	按公开凭证顺序解析	仅用于本次查询
`--format <fmt>`	枚举	否	auto	auto、table、json、text

`task_status`	CLI 结果	退出码	后续处理
`PENDING` / `RUNNING`	输出当前状态	0	稍后再次运行 `task get`
`SUCCEEDED`	输出归一化结果；按识别出的类型处理 URL、文本或文件	0，仅限后续处理成功	使用输出的 path 或 URL
`FAILED`	输出远端 `code` 和 `message`（如有）；上游 `CANCELED` 也归入此状态	1	根据失败原因修改请求
`UNKNOWN` 或缺失	输出归一化的 `UNKNOWN`	0	用 `--format json` 检查结果，不把未知状态当作成功完成

完全省略 <task-id> 时由参数解析器报错并退出 1；显式传入空白字符串时报 INVALID_ARGUMENT 并退出 4。CLI 根据结果 URL 的扩展名推断 video、model3d、audio、transcription 或 image；无法识别时不猜测类型，也不保证下载。国内站的 task get 在 SUCCEEDED 时，会把已识别的 image、video、audio 和 model3d 结果自动下载到 --out 或当前目录。3D 多文件结果保存在 data.files[]，模型文件与预览图都会处理；非 3D 多 URL 结果会全部下载，但规范化结果只公开第一个 URL 和 path。给多文件结果传入单一文件名时，第一个文件使用该名称，后续文件在名称后追加序号。transcription 不下载完整 JSON，但会尝试读取并展示最多 200 个字符的转写预览，失败时保留 URL。远端任务返回 SUCCEEDED 后，下载 HTTP 失败仍会使 CLI 退出 3，写盘失败通常退出 1，因此任务成功不等于本次命令和本地文件处理都成功。JSON 输出是 {meta,data} 归一化结果，不是服务端原始响应。本命令没有上传型输入；--out 只是结果位置。异步任务的参数和结果字段以创建任务时所用模型的 API 参数页为准；3D 可参见 Tripo 查询结果，其他任务从对应命令末尾的模态入口进入查询文档。

用量、账单与订阅

想知道本月用了多少、花了多少、哪个模型或 API Key 成本最高，或订阅额度还剩多少？用这组命令。

日期选项以各命令表为准：usage summary 的日期只作用于 PAYG，usage free-tier 当前仅返回快照；其余相关查询按 --from/--to > --days > --period > 本月至今解析。常用 --period 值包括 today、yesterday、week、month、last-month、quarter、year 和 YYYY-MM。金额不再固定舍入为四位小数；JSON 中 cost 仍为 number。

usage summary

汇总免费额度、Token Plan 与按量付费用量。

qianwen usage summary [--from <date>] [--to <date>] [--period <preset>] [--format <auto|table|json|text>]

qianwen usage summary --period month
qianwen usage summary --from 2026-07-01 --to 2026-07-21 --format json

Flag	类型	必填	默认	说明
`--from <date>`	日期	否	当月首日	PAYG 开始日期，YYYY-MM-DD
`--to <date>`	日期	否	今天	PAYG 结束日期，YYYY-MM-DD
`--period <preset>`	字符串	否	month	PAYG 预设区间或 YYYY-MM

日期参数及 JSON 顶层 period 仅界定 pay_as_you_go；free_tier 与 token_plan 为查询时的当前快照。 JSON 输出结构示例（已订阅场景；示例值仅用于说明字段）：

{
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-21"
  },
  "free_tier": [
    {
      "model_id": "qwen-plus",
      "quota": {
        "remaining": 850000,
        "total": 1000000,
        "unit": "tokens",
        "used_pct": 15,
        "status": "valid",
        "resetDate": "2026-08-01T00:00:00.000Z"
      }
    }
  ],
  "token_plan": {
    "subscribed": true,
    "planName": "Token Plan",
    "status": "valid",
    "totalCredits": 25000,
    "remainingCredits": 18000,
    "usedPct": 28,
    "resetDate": "2026-08-01T00:00:00.000Z"
  },
  "pay_as_you_go": {
    "models": [
      {
        "model_id": "qwen-plus",
        "usage": {
          "tokens": 600000
        },
        "cost": 0.38,
        "currency": "CNY"
      }
    ],
    "total": {
      "cost": 0.38,
      "currency": "CNY"
    }
  }
}

模型无免费额度时 free_tier[].quota 为 null；token_plan 仅 subscribed 必有，其余字段按数据条件出现；pay_as_you_go 的计量字段随模型计费方式变化。发现某个模型用量异常时，运行 qianwen usage breakdown --model <id>；需要查看请求级原因时，继续用 qianwen usage logs。

usage breakdown

查看指定模型按日、月或季度拆分的按量付费用量。

qianwen usage breakdown --model <id> [--granularity <day|month|quarter>] [--from <date>] [--to <date>] [--period <preset>] [--days <number>] [--format <auto|table|json|text>]

qianwen usage breakdown --model qwen-plus --days 7
qianwen usage breakdown --model qwen-plus --granularity month --period quarter

Flag	类型	必填	默认	说明
`--model <id>`	字符串	是	无	模型 ID；运行时校验
`--granularity <g>`	枚举	否	day	day、month、quarter
`--from <date>`	日期	否	未设置	开始日期
`--to <date>`	日期	否	未设置	结束日期
`--period <preset>`	字符串	否	month	预设区间
`--days <number>`	数值	否	未设置	向前回看天数；请传正整数，CLI 当前未严格校验整数性

usage free-tier

浏览全部模型的当前免费额度状态。

qianwen usage free-tier [--from <date>] [--to <date>] [--period <preset>] [--format <auto|table|json|text>]

qianwen usage free-tier --format json

Flag	类型	必填	默认	说明
`--from <date>`	日期	否	未设置	已注册；当前不影响返回的额度快照
`--to <date>`	日期	否	未设置	已注册；当前不影响返回的额度快照
`--period <preset>`	字符串	否	未设置	已注册；当前不影响返回的额度快照

该命令始终返回当前免费额度快照；日期 Flag 当前不会筛选历史额度。

usage payg

浏览全部模型的按量付费用量。

qianwen usage payg [--from <date>] [--to <date>] [--period <preset>] [--days <number>] [--format <auto|table|json|text>]

qianwen usage payg --period last-month
qianwen usage payg --days 30 --format json

Flag	类型	必填	默认	说明
`--from <date>`	日期	否	未设置	开始日期
`--to <date>`	日期	否	未设置	结束日期
`--period <preset>`	字符串	否	month	预设区间
`--days <number>`	数值	否	未设置	向前回看天数；请传正整数，CLI 当前未严格校验整数性

usage logs

按时间、模型、状态或请求 ID 查询调用日志。

qianwen usage logs [--from <date-or-rfc3339>] [--to <date-or-rfc3339>] [--period <preset>] [--model <id>]... [--status <type>]... [--request-id <id>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qianwen usage logs --period 24h --status 4xx --status 5xx
qianwen usage logs --request-id 12345-abcdef --format json

Flag	类型	必填	默认	说明
`--from <value>`	日期/时间	否	7 天前 00:00	YYYY-MM-DD 或 RFC3339
`--to <value>`	日期/时间	否	当前时间	YYYY-MM-DD 或 RFC3339
`--period <preset>`	字符串	否	未设置	支持 `1h`、`24h`、`7d` 及日期预设
`--model <id>`	可重复字符串	否	未设置	模型过滤，可重复
`--status <type>`	可重复字符串	否	未设置	支持 0/cancel、2xx/success、4xx/client-error、5xx/server-error 及别名；未知值被忽略
`--request-id <id>`	字符串	否	未设置	精确请求 ID；设置后忽略其他过滤项
`--page <integer>`	整数	否	1	页码
`--page-size <integer>`	整数	否	20	每页 1-100 条

单次时间跨度最多 14 天。

billing summary

按结算月份汇总账单金额。

qianwen billing summary [--from <yyyy-mm>] [--to <yyyy-mm>] [--charge-type <all|subscription|payg>] [--format <auto|table|json|text>]

qianwen billing summary --from 2026-06 --to 2026-07

Flag	类型	必填	默认	说明
`--from <yyyy-mm>`	月份	否	当前月	起始结算月
`--to <yyyy-mm>`	月份	否	当前月	结束结算月，含当月
`--charge-type <type>`	枚举	否	all	all、subscription、payg

--from 和 --to 必须使用 YYYY-MM，月份范围为 01-12；非法值返回退出码 4，错误 code 为 INVALID_ARGUMENT。区间内缺少账单记录的月份仍会补齐：table/text 显示 No bill，JSON 补齐项使用账期 YYYYMM、aftertaxAmount: null 和 settled: false；真实零元账单保留非 null 的金额字符串，并使用 settled: true。totals 只汇总 settled: true 的月份。需要定位费用来源时，运行 qianwen billing breakdown --group-by model 或 --group-by api-key。

billing breakdown

按模型或 API Key 拆分消费。

qianwen billing breakdown [--granularity <day|month>] [--group-by <model|api-key>] [--from <date>] [--to <date>] [--period <preset>] [--charge-type <all|subscription|payg>] [--top <integer>] [--format <auto|table|json|text>]

qianwen billing breakdown --group-by api-key --top 20
qianwen billing breakdown --granularity day --period week

Flag	类型	必填	默认	说明
`--granularity <g>`	字符串（day/month）	否	month	day 或 month；其他值静默回退为 month
`--group-by <dim>`	枚举	否	model	model 或 api-key
`--from <date>`	日期/月	否	当前月	day 使用 YYYY-MM-DD；month 可用 YYYY-MM
`--to <date>`	日期/月	否	当前月	结束日期或月份
`--period <preset>`	字符串	否	未设置	today、yesterday、week、this-week、month、this-month、last-month、quarter、year 或 YYYY-MM
`--charge-type <type>`	枚举	否	all	all、subscription、payg
`--top <integer>`	整数	否	10	返回前 N 项；仅数字小于 1 或大于 20 时报错退出 4。非数字输入回退默认 10，非整数取整数部分，均不报错

day 粒度下起止日期相差不超过 31 天，month 粒度下起止月份相差不超过 12 个月（含首尾最多覆盖 32 个自然日或 13 个账期月）；day 跨度超限返回退出码 4，month 跨度超限返回退出码 1。周期按名称分类：today、yesterday、week、this-week 为短周期；month、this-month、last-month、quarter、year 为长周期。自定义 YYYY-MM 按实际跨度判断，完整自然月归为短周期。仅传 --period 且未显式指定粒度时，短周期自动使用 day，长周期使用 month；短周期配 month 或长周期配 day 时返回退出码 4，错误 code 为 INVALID_ARGUMENT。 --top 超出 1-20 或 --period 不在上述范围时返回退出码 4，错误 code 为 INVALID_ARGUMENT。Top N 行合计小于权威总额时，CLI 会追加 UNLISTED / Unlisted 差额行；该行不计入 N 或 totalRows，每个周期最多返回 N+1 行。

billing limit

查看消费上限和告警配置。

qianwen billing limit [--format <auto|table|json|text>]

qianwen billing limit --format json

billing balance summary

查看账号可用余额。

qianwen billing balance summary [--format <auto|table|json|text>]

qianwen billing balance summary

余额不足时，可运行 qianwen billing balance recharge 打开充值页，也可按下一节说明在终端创建支付宝充值订单。

billing balance recharge

打开原有网页充值页，或在终端创建支付宝充值订单。

qianwen billing balance recharge [--channel <channel>] [--amount <amount>] [--format <auto|table|json|text>]

qianwen billing balance recharge --channel alipay --amount 10.00 --format table
qianwen billing balance recharge --channel alipay --amount 10.00 --format json

Flag	类型	必填	默认	说明
`--channel <channel>`	枚举	条件必填	未设置	终端充值渠道；当前仅支持 `alipay`，必须与 `--amount` 同时提供
`--amount <amount>`	金额字符串	条件必填	未设置	CNY 金额；最小 `0.01`，最多两位小数，必须与 `--channel` 同时提供
`--format <fmt>`	枚举	否	auto	auto、table、json、text

运行 qianwen billing balance recharge 且不传 --channel、--amount 时，仍打开网页充值页。终端建单必须同时提供两项参数，金额如 10、10.50 有效，0、1.234 无效。table 显示付款入口并等待；JSON 立即返回 rechargeOrderId 和支付链接；text 显示金额和支付链接后立即返回。无论使用哪种格式，用户都需在指定的充值渠道确认付款。常见报错：

情况	提示或退出码	处理方式
参数缺失、渠道或金额非法	`INVALID_ARGUMENT`，退出 1	同时传入 `--channel alipay` 和有效金额
未登录或认证失败	退出 2	先完成登录，再重新建单
建单结果无法确认	`CREATE_UNKNOWN`	不要立即重新建单，先查充值记录和余额

billing balance recharge-history

分页查询充值记录。

qianwen billing balance recharge-history [--range <1d|3d|7d|30d>] [--start-time <time> --end-time <time>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qianwen billing balance recharge-history --range 7d --page 1 --page-size 20
qianwen billing balance recharge-history --start-time "2026-08-01 09:30:00" --end-time 2026-08-31T18:00:00 --format json

Flag	类型	必填	默认	说明
`--range <range>`	枚举	否	30d	Asia/Shanghai 自然日范围：1d、3d、7d、30d
`--start-time <time>`	日期或时间	条件必填	未设置	包含的起点；必须与 `--end-time` 同时提供，不能与 `--range` 共用
`--end-time <time>`	日期或时间	条件必填	未设置	包含的终点；必须与 `--start-time` 同时提供，不能与 `--range` 共用
`--page <integer>`	正整数	否	1	页码
`--page-size <integer>`	正整数	否	10	每页记录数
`--format <fmt>`	枚举	否	auto	auto、table、json、text

默认查询最近 30 个 Asia/Shanghai 自然日。--range 与显式起止时间互斥，--start-time、--end-time 必须成对出现；日期接受 YYYY-MM-DD，日期时间可用 T 或空格分隔。JSON 不返回充值订单 ID。常见报错：

情况	提示或退出码	处理方式
时间参数组合错误、范围或日期非法	`INVALID_ARGUMENT`，退出 1	选择 `--range`，或同时提供有效的起止时间
页码或每页数量不是正整数	`INVALID_ARGUMENT`，退出 1	将 `--page`、`--page-size` 改为正整数

subscription status

汇总订阅状态；仅支持 Token Plan。

qianwen subscription status [--plan <token>] [--format <auto|table|json|text>]

qianwen subscription status --plan token --format json

Flag	类型	必填	默认	说明
`--plan <token>`	字符串（token）	否	全部支持的计划	仅识别 token；其他值按未设置处理，不报错

使用团队 Token Plan 时，运行 qianwen subscription tokenplan seats --format json 查看席位实例。

subscription orders

列出订阅的购买、续费和升级订单。

qianwen subscription orders [--from <date>] [--to <date>] [--type <purchase|renew|upgrade>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qianwen subscription orders --type purchase --page 1 --page-size 20

Flag	类型	必填	默认	说明
`--from <date>`	日期	否	未设置	开始日期，YYYY-MM-DD
`--to <date>`	日期	否	未设置	结束日期，YYYY-MM-DD
`--type <kind>`	字符串	否	未设置	识别 purchase、renew、upgrade；其他值按未设置处理，不报错
`--page <integer>`	整数	否	1	页码
`--page-size <integer>`	整数	否	20	每页 1-100 条；超过 100 返回退出码 4

--from/--to 不做本地严格校验；无法解析的值会被忽略，对应过滤可能不生效。

subscription tokenplan status

查看 Token Plan 席位类型、周期、续费状态与诊断信息。

qianwen subscription tokenplan status [--format <auto|table|json|text>]

qianwen subscription tokenplan status --format json

自动续费明确关闭时，seatSummary.groups[].nextCycleFlushTime 为 null。

subscription tokenplan seats

分页列出 Token Plan 席位实例。

qianwen subscription tokenplan seats [--spec-type <pro|standard>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qianwen subscription tokenplan seats --spec-type pro --format json

Flag	类型	必填	默认	说明
`--spec-type <type>`	枚举	否	未设置	pro 或 standard（不区分大小写）；其他值返回退出码 4
`--page <integer>`	整数	否	1	页码
`--page-size <integer>`	整数	否	20	每页最多 100 条

该命令未显式指定格式时默认使用 table；Agent 应显式传 --format json。

配置、诊断与补全

想固定机器可读输出、排查本地环境、启用 Shell 补全或确认版本？用这组命令。

config list

列出用户可配置项；1.4.0 公开键仅有 output.format。

qianwen config list [--format <auto|table|json|text>]

qianwen config list --format json

config get

读取一个配置值。

qianwen config get <key> [--format <auto|table|json|text>]

qianwen config get output.format

config set

设置一个配置值。

qianwen config set <key> <value> [--format <auto|table|json|text>]

qianwen config set output.format json

output.format 可取 auto、table、json、text。设置后运行 qianwen config get output.format 确认生效。

config unset

删除配置值并恢复默认行为。

qianwen config unset <key> [--format <auto|table|json|text>]

qianwen config unset output.format

doctor

检查版本、认证、Token、网络、Shell 补全和全局配置。

qianwen doctor [--format <auto|table|json|text>]

qianwen doctor --format json

按诊断结果修复后重新运行 qianwen doctor，直到失败项消失。

completion install

为当前或指定 Shell 安装命令补全。

qianwen completion install [--shell <bash|zsh|fish>]

qianwen completion install --shell zsh

completion generate

输出当前或指定 Shell 的补全脚本。

qianwen completion generate [--shell <bash|zsh|fish>]

qianwen completion generate --shell bash

--shell 省略时自动检测，支持 bash、zsh、fish。

version

输出版本；--check 同时检查新版本。

qianwen version [--check]

qianwen version --check

技能市场

想从技能市场查找 Agent Skills，并安装到当前项目或本机 Agent 的技能目录？从这里开始。

这组命令无需登录。搜索不会修改本地文件；新装或更新时下载技能包并校验 SHA256，并只管理带有效 CLI 元数据的同名目录。

skills search

按关键词搜索技能市场；query 可省略，精确且大小写一致的 slug 会排在结果首位。

qianwen skills search [query] [--limit <integer>] [--format <auto|table|json|text>]

qianwen skills search qianwen --limit 10
qianwen skills search 文本生成
qianwen skills search qianwen-text --format json

Flag / 参数	类型	必填	默认	说明
`[query]`	字符串	否	空字符串	搜索词，可为中文或英文，支持模糊匹配；省略时按空字符串搜索
`--limit <integer>`	整数	否	5	最多返回条数，接受 1-50 的整数

table 模式使用可滚动的交互表格；text 和 JSON 适合非交互环境。 JSON 输出结构示例（示例值仅用于说明字段）：

{
  "query": "qianwen-text",
  "results": [
    {
      "slug": "qianwen-text",
      "name": "千问-文本生成",
      "description": "技能说明",
      "publisher": "千问AI平台",
      "currentVersion": "0.0.1",
      "verified": true
    }
  ]
}

currentVersion 在平台未返回版本时省略。--limit 不是整数或超出 1-50 时返回退出码 1，错误 code 为 INVALID_ARGUMENT；网络、平台及服务端错误（含技能不存在、限流）均归一为退出码 3。没有匹配项时返回空的 results 数组并退出 0。找到 slug 后，运行 qianwen skills install <slug> 安装技能。

skills install

下载并安装一个技能；slug 只能包含字母、数字、连字符或下划线，长度 1-64，首尾必须是字母或数字。

qianwen skills install <slug> [--dir <directory>] [--format <auto|table|json|text>]

qianwen skills install qianwen-text
qianwen skills install qianwen-text --dir . --format json

Flag / 参数	类型	必填	默认	说明
`<slug>`	字符串	是	无	技能 slug
`--dir <directory>`	路径	否	当前目录	安装基目录；显式指定时必须已存在且可写，目标为 `<directory>/<slug>`

table 模式下，未传 --dir 且当前目录不是已知 Agent 技能目录时出现选择界面：←/→ 在"继续当前目录"与"选择目标 Agent"之间切换（Enter 确认、Esc 取消）；选择 Agent 后用 ↑/↓ 在其列表中导航（Esc 返回上一层），安装到该 Agent 相对当前工作目录的技能目录。选择界面不接受手动输入路径；要指定其他目录，用 --dir 重跑。JSON/text 模式不显示选择界面，默认安装到当前目录下。 JSON 输出结构示例（示例值仅用于说明字段）：

{
  "slug": "qianwen-text",
  "version": "0.0.1",
  "outcome": "updated",
  "targetDir": "/path/to/project/.claude/skills/qianwen-text",
  "security": "安全",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "downgrade": {
    "from": "0.0.2",
    "to": "0.0.1"
  }
}

targetDir 为实际安装目录：默认当前目录，table 模式选择 Agent 后为该 Agent 相对当前工作目录的技能目录，传 --dir 时为指定目录，末尾均为 /<slug>。outcome 为 installed、updated 或 noop；noop 表示同版本已安装，不写入文件。只有检测到降级更新时才出现 downgrade，CLI 同时给出警告；security 显示平台安全状态。下载包必须通过平台声明值与本地计算值的 SHA256 比对。目标同名目录没有有效 CLI 元数据时返回 UNMANAGED_CONFLICT，不会覆盖或修改该目录。 slug 格式不合法返回 INVALID_ARGUMENT（以 - 开头的输入会被当作未知选项，返回 UNKNOWN_OPTION，同样退出 1）；目录不存在或不是目录返回 INSTALL_DIR_NOT_FOUND；目录不可写返回 INSTALL_DIR_NOT_WRITABLE。这三类本地校验均退出 1，错误写入 stderr，且在此之前不发出任何网络请求。技能包下载、SHA256 校验或安装失败退出 1；技能市场接口（搜索、详情、下载链接）的网络、平台及服务端错误（含技能不存在、限流）均归一为退出码 3。

支持与更新

想提交并跟进问题、关闭或评价工单，或检查 CLI 更新？从这里选择动作。

support list

分页列出支持工单。

qianwen support list [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qianwen support list --page 1 --page-size 10

Flag	类型	必填	默认	说明
`--page <integer>`	整数	否	1	页码
`--page-size <integer>`	整数	否	10	每页 1-10 条

support view

查看工单详情和消息记录。

qianwen support view <ticket-id> [--format <auto|table|json|text>]

qianwen support view TICKET_ID --format json

support create

交互式创建工单，或用成对参数进行非交互创建。

qianwen support create [--list-categories] [--category-id <id>] [--description <text>] [--accept-language <zh_CN|en_US>] [--format <auto|table|json|text>]

qianwen support create --list-categories
qianwen support create --category-id CATEGORY_ID --description "问题描述" --accept-language zh_CN

Flag	类型	必填	默认	说明
`--list-categories`	布尔	否	false	列出分类后退出
`--category-id <id>`	字符串	非交互条件必填	无	与 `--description` 同时提供
`--description <text>`	字符串	非交互条件必填	无	最长 2000 字符，超长截断
`--accept-language <lang>`	枚举	否	zh_CN	工单语言：zh_CN 或 en_US；区分大小写

仅给 --category-id/--description 之一返回退出码 1；两者均未提供且非 TTY 返回退出码 4。 --accept-language 使用其他值时返回退出码 1，错误 code 为 INVALID_ARGUMENT。创建成功后保存返回的工单 ID，并运行 qianwen support view <ticket-id> 跟进处理记录。

support reply

回复工单；非交互环境必须提供消息正文。

qianwen support reply <ticket-id> [--message <text>] [--format <auto|table|json|text>]

qianwen support reply TICKET_ID --message "请检查日志"

Flag / 参数	类型	必填	默认	说明
`<ticket-id>`	字符串	是	无	工单 ID
`--message <text>`	字符串	非交互必填	无	最长 2000 字符，超长截断

非交互缺少 --message 返回退出码 4。

support close

关闭工单；脚本中必须用 --yes 跳过确认。

qianwen support close <ticket-id> [--yes] [--format <auto|table|json|text>]

qianwen support close TICKET_ID --yes

Flag / 参数	类型	必填	默认	说明
`<ticket-id>`	字符串	是	无	工单 ID
`--yes`	布尔	非交互必填	false	跳过确认

非交互缺少 --yes 返回退出码 4。

support rate

对已解决工单评分；评分范围为 0-2。

qianwen support rate <ticket-id> [--rating <0|1|2>] [--comment <text>] [--format <auto|table|json|text>]

qianwen support rate TICKET_ID --rating 2 --comment "满意"

Flag / 参数	类型	必填	默认	说明
`<ticket-id>`	字符串	是	无	工单 ID
`--rating <n>`	整数	非交互必填	无	0=不满意，1=一般，2=满意
`--comment <text>`	字符串	否	未设置	最长 500 字符，超长截断

非交互缺少 --rating、非整数或越界均返回退出码 1，code 为 INVALID_ARGUMENT。

update

检查版本并输出升级提示，不直接安装。版本比对来自 GitHub Releases；检测到新版本时按安装渠道输出升级命令：Node.js 安装按模块路径提示 npm、pnpm 或 Bun，Bun 单文件版本按平台提示运行 install.sh 或 install.ps1。检查请求失败或新版本尚未发布时按已是最新处理、不提示，核对版本以发布页为准。

qianwen update

qianwen update

全局约定

qianwen [--format <auto|table|json|text>] [--quiet] <area> <verb> [args] [flags]

全局 Flag	类型	默认	说明
`--format <fmt>`	枚举	auto	显式格式优先于 `config output.format`
`-q, --quiet`	布尔	false	静默 stdout/stderr，仅以退出码表示结果
`-v, --version`	布尔	false	顶层版本快捷项
`-h, --help`	布尔	false	顶层及各级命令帮助

auto 在 TTY 使用 table，在 pipe/重定向中使用 JSON；非 TTY 显式请求 table 时降级为 text 并在 stderr 提示。成功数据写 stdout，错误和诊断写 stderr。JSON 结构由各命令定义，不提供统一外层 envelope；CliError 的退出码字段为 exit_code，Commander 参数错误仍可能使用 exitCode。模型调用的普通成功 JSON 使用 {meta,data}，普通错误 JSON 使用 {error:{code,message,model?,hint?,exit_code}}；chat create --stream --format json 例外，输出逐行 NDJSON。主动使用 --no-wait 并成功提交时退出 0；Video、异步 ASR 和 3D 等待超时退出 8，Image 异步等待超时当前输出未完成状态并退出 0。HTTP 2xx、退出 0 或 task id 只说明请求到达相应阶段，不证明任务完成或模型采用了每个参数。分页查询中，JSON 通常保留请求页并在越界时返回空数组；交互表格通常调整到有效页。Agent 应显式指定 --format json、页码和每页数量。

退出码	含义
0	成功
1	通用错误；Commander 参数解析错误也使用 1
2	认证失败（`docs search` 空查询也退出 2）
3	网络错误
4	配置或参数错误
5	限流
6	服务端错误
7	资源未找到
8	操作未完成的保留码
10	`docs view` 文档未找到或内容获取失败（超时退出 3）
130	用户中断

本地校验的退出码尚未完全统一：billing summary 的月份格式、billing breakdown 的周期/粒度冲突/top 越界、usage logs 的周期或跨度错误、subscription orders 的 --page-size 超限、subscription tokenplan seats 的 --spec-type 非法、support reply/close 非交互缺必填参数、support create 缺成对参数且非 TTY，返回 4，错误 code 为 INVALID_ARGUMENT；skills search --limit 的非法值或 skills install 的 slug 格式错误返回 1，错误 code 为 INVALID_ARGUMENT，目录错误返回 1，错误 code 为 INSTALL_DIR_NOT_FOUND 或 INSTALL_DIR_NOT_WRITABLE；support create --accept-language 非法值返回 1，错误 code 为 INVALID_ARGUMENT；docs search "" 返回纯文本错误并退出 2，不含 JSON code。进程非 0 表示命令执行错误或中断；退出 0 不一定代表异步任务或支付业务成功。其他命令失败时，可结合 JSON 错误对象中的 code 分流。auth status 未登录或凭证过期也退出 0，必须读取 authenticated。skills 两命令将技能市场接口错误（含技能不存在、限流）归一为退出码 3，不沿用表中 5/6/7；技能包下载失败仍为 1。

附录

命令速查表

命令	用途
`qianwen auth login`	获取并保存管理凭证
`qianwen auth logout`	删除本地凭证并注销
`qianwen auth status`	检查凭证与服务端验证状态
`qianwen models list`	筛选可用模型
`qianwen models info`	查看单模型完整详情
`qianwen models search`	按关键词或模态找模型
`qianwen chat create`	发起文本或多媒体对话
`qianwen image generate`	生成或编辑图像
`qianwen video generate`	提交文生视频或图生视频任务
`qianwen audio transcribe`	转写录音文件或音频 URL
`qianwen audio speech`	将文本合成为本地音频文件
`qianwen model3d generate`	通过文本或单图生成 3D 模型
`qianwen music generate`	根据提示词或原生请求生成音乐
`qianwen task get`	单次查询异步任务状态与结果
`qianwen usage summary`	汇总各计费方式用量
`qianwen usage breakdown`	拆分指定模型用量
`qianwen usage free-tier`	检查免费额度余额
`qianwen usage payg`	查看按量付费用量与成本
`qianwen usage logs`	按请求或状态查调用日志
`qianwen billing limit`	检查消费上限与告警
`qianwen billing breakdown`	按模型或 API Key 拆账
`qianwen billing summary`	查看月度结算总额
`qianwen billing balance summary`	检查账号可用余额
`qianwen billing balance recharge`	打开充值页或创建支付宝充值订单
`qianwen billing balance recharge-history`	分页查询充值记录
`qianwen subscription status`	确认 Token Plan 订阅状态
`qianwen subscription orders`	查购买、续费和升级订单
`qianwen subscription tokenplan status`	查周期与续费状态
`qianwen subscription tokenplan seats`	逐页查看席位实例
`qianwen workspace list`	列出可访问空间
`qianwen workspace limit`	检查空间数量上限
`qianwen support list`	分页查工单
`qianwen support view`	查看工单与消息记录
`qianwen support create`	提交新工单
`qianwen support reply`	向工单追加消息
`qianwen support close`	关闭工单请求
`qianwen support rate`	评价已解决工单
`qianwen docs search`	按关键词找官方文档
`qianwen docs view`	打开文档正文
`qianwen config list`	查看公开配置项
`qianwen config get`	读取单项配置
`qianwen config set`	设置默认输出格式
`qianwen config unset`	恢复配置默认值
`qianwen doctor`	定位版本、认证或网络问题
`qianwen completion install`	启用 Shell 补全
`qianwen completion generate`	导出 Shell 补全脚本
`qianwen version`	查看版本并检查更新
`qianwen update`	获取升级提示
`qianwen skills search`	搜索技能市场技能
`qianwen skills install`	下载并安装技能市场技能

​快速开始

​模型与文档

​models list

​models info

​models search

​docs search

​docs view

​认证、账号与空间

​auth login

​auth status

​auth logout

​workspace list

​workspace limit

​模型调用

​chat create

​image generate

​video generate

​audio transcribe

​audio speech

​model3d generate

​music generate

​task get

​用量、账单与订阅

​usage summary

​usage breakdown

​usage free-tier

​usage payg

​usage logs

​billing summary

​billing breakdown

​billing limit

​billing balance summary

​billing balance recharge

​billing balance recharge-history

​subscription status

​subscription orders

​subscription tokenplan status

​subscription tokenplan seats

​配置、诊断与补全

​config list

​config get

​config set

​config unset

​doctor

​completion install

​completion generate

​version

​技能市场

​skills search

​skills install

​支持与更新

​support list

​support view

​support create

​support reply

​support close

​support rate

​update

​全局约定

​附录

​命令速查表