Skip to main content
阿里云百炼 home page阿里云百炼
使用 API

使用百炼 CLI

阿里云百炼 CLI 是阿里云百炼平台专为 AI Agent 打造的命令行工具。只需一行安装指令并完成认证，即可将百炼平台的 AI 能力集成至各类 AI 工具中。

安装与配置

安装

前置要求：Node.js ≥ 22.12.0。百炼 CLI 仅支持通过 npm 安装。
方式一：在 AI Agent 中安装（推荐） 在 AI Agent 中告诉 Agent： 
请阅读 https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI
方式二：手动安装 
# 第 1 步：安装 CLI
npm install -g bailian-cli

# 第 2 步：安装 Skills（将百炼能力描述文件注册到各 Agent 的 Skills 目录）
npx skills add modelstudioai/cli --all -g

# 第 3 步：验证安装
bl --version

认证与配置

使用百炼 CLI 前，您需要完成身份认证。支持以下认证方式：

认证方式

命令

适用场景

控制台登录（推荐）

bl auth login --console

模型调用 + 应用管理（拉起浏览器完成 OAuth 登录）

API Key

bl auth login --api-key sk-xxx（获取 API Key）

模型调用（文本、图像、视频、语音等）

Token Plan API Key

bl auth login --config token-plan --api-key sk-sp-xxx（获取 Token Plan API Key）

Token Plan 个人版订阅用户的模型调用。使用 bl config use --name token-plan 切换为默认配置，或在命令中加 --config token-plan 单次指定

环境变量

配置 API Key 环境变量

CI/CD、无界面环境

配置文件

bl config set --key api_key --value sk-xxx

持久化（不校验 Key 有效性）

临时传入

bl text chat --api-key sk-xxx --message "你好"

单次调用，不落盘

控制台登录和 API Key 可同时配置，互不覆盖。
如果您通过控制台登录后，执行 bl text chat 等模型调用命令时仍提示"缺少 API Key"，请先运行 bl update 升级到最新版本。若升级后问题仍然存在，请单独配置 API Key：bl auth login --api-key <your-key>。
认证完成后，您可以通过 bl config 设置模型、输出目录等参数： 
# 查看当前配置
bl config show

# 设置默认文本模型
bl config set --key default-text-model --value qwen3.7-max

# 设置输出目录
bl config set --key output_dir --value ~/bailian-output

参数

说明

--api-key <key>

指定 API Key（仅本次生效）

--region <cn|us|intl>

切换地域（默认 cn）

--base-url <url>

自定义 API 端点

--output <text|json>

输出格式

--timeout <seconds>

请求超时时间

--quiet

静默模式，减少输出

--verbose

打印 HTTP 请求/响应详情

--no-color

禁用 ANSI 颜色

--dry-run

预览请求，不实际执行

--non-interactive

非交互模式，适用于 Agent 和 CI/CD

--concurrent <n>

并发请求数（默认 1）

百炼 CLI 兼容 Claude Code、Cursor、Codex、Qwen Code 等主流 AI 工具和框架。完整兼容列表和集成方式，请参见百炼 CLI GitHub 仓库。

场景实战

电商套图生成

告诉 Agent： 
帮我生成一套亚马逊电商主图，6 张图，产品是纯黑色夏日男装 T 恤
Agent 会组合多个命令完成任务：
  1. 生成 6 张产品主图：
 bl image generate --prompt "纯黑色夏日男装T恤，白色背景，亚马逊电商主图风格" --n 6 --out-dir ./ecommerce/
  1. 如需调整某张图：
 bl image edit --image ./ecommerce/image_01.png --prompt "添加模特穿着效果"
  1. 如需生成产品展示视频：
 bl video generate --image ./ecommerce/image_01.png --prompt "T恤360度旋转展示" --download tshirt-demo.mp4

新闻播客生成

告诉 Agent： 
搜索今天关于 AI 的新闻，写一段相声，然后生成男女音色区分的音频播客
Agent 会依次执行：
  1. 联网搜索获取新闻素材：
 bl search web --query "今天AI新闻"
  1. 用大模型撰写相声稿本：
 bl text chat --message "根据以下新闻素材，写一段相声..."
  1. 分角色生成音频：
 bl speech synthesize --text "甲：您听说了吗..." --voice Ethan --out host_male.mp3
 bl speech synthesize --text "乙：怎么了？..." --voice Cherry --out host_female.mp3
  1. 用 ffmpeg 合并音频片段为完整播客。

故事书生成

告诉 Agent： 
帮我生成一部小红帽的故事书，真人写实版本，保持人物连续一致性，需要有 20 页，尺寸是 16:9 的，变成 PDF 给我
Agent 会自动完成：为每页生成故事文字 → 根据文字生成风格一致的配图 → 排版并输出 PDF。

命令参考

文本对话

bl text chat 发送文本对话请求，兼容 OpenAI 接口格式。 
bl text chat --message <text> [flags]

参数

说明

默认值

--model <model>

模型 ID

qwen3.7-max

--message <text>

消息内容（可重复，前缀 role: 设置角色）

—

--messages-file <path>

从 JSON 文件读取消息（- 表示标准输入）

—

--system <text>

系统提示词

—

--max-tokens <n>

最大生成 token 数

4096

--temperature <n>

采样温度 (0.0, 2.0]

—

--top-p <n>

核采样阈值

—

--stream

流式输出（TTY 下默认开启）

—

--tool <json-or-path>

工具定义，JSON 或文件路径（可重复）

—

--enable-thinking

开启思考模式（适用于 qwen3/qwq 模型）

—

--thinking-budget <n>

思考模式最大 token 数

4096

全模态理解

bl omni 全模态对话，支持图片、音频、视频输入，文本和语音输出。 
bl omni --message <text> [flags]

参数

说明

默认值

--message <text>

消息内容（可重复）

—

--model <model>

模型 ID

qwen3.5-omni-plus

--system <text>

系统提示词

—

--image <url>

图片 URL 或本地文件（可重复）

—

--audio <url>

音频 URL 或本地文件（可重复）

—

--video <url>

视频 URL 或本地文件

—

--voice <voice>

输出音色（可选：Chelsie、Cherry、Ethan、Serena、Tina）

Cherry

--audio-format <fmt>

音频输出格式

wav

--audio-out <path>

保存音频到文件

自动生成

--text-only

仅输出文本，不生成音频

—

--max-tokens <n>

最大生成 token 数

—

--temperature <n>

采样温度 (0.0, 2.0]

—

图像生成与编辑

bl image generate 文字生成图像。 
bl image generate --prompt <text> [flags]

参数

说明

默认值

--prompt <text>

图像描述

—

--model <model>

模型 ID

qwen-image-2.0

--size <W*H>

图像尺寸，支持比例（3:4, 16:9）或像素（2048*2048）

—

--n <count>

每次生成图片数量（最多 6）

1

--seed <n>

随机种子，用于复现结果

—

--negative-prompt <text>

反向提示词，排除不需要的内容

—

--prompt-extend <bool>

是否启用提示词扩展

true（同步模式）

--watermark <bool>

是否添加水印

true

--no-wait

异步模式，立即返回任务 ID

—

--out-dir <dir>

图片保存目录

—

--out-prefix <prefix>

文件名前缀

image

--poll-interval <seconds>

轮询间隔

3

bl image edit 编辑已有图像，支持多图合成。 
bl image edit --image <url> --prompt <text> [flags]

参数

说明

默认值

--image <url>

源图片 URL 或本地文件（可重复，用于多图合成）

—

--prompt <text>

编辑指令

—

--model <model>

模型 ID

qwen-image-2.0

--size <W*H>

输出尺寸

—

--n <count>

生成数量（最多 6）

1

--seed <n>

随机种子

—

--negative-prompt <text>

反向提示词

—

--prompt-extend <bool>

是否启用提示词扩展

true

--watermark <bool>

是否添加水印

true

--out-dir <dir>

保存目录

—

--out-prefix <prefix>

文件名前缀

edited

视频生成与编辑

bl video generate 文字或图片生成视频。 
bl video generate --prompt <text> [--image <url>] [flags]

参数

说明

默认值

--prompt <text>

视频描述

—

--model <model>

模型 ID

happyhorse-1.1-t2v（有 --image 时为 i2v）

--image <url>

输入图片，启用图生视频模式

—

--negative-prompt <text>

反向提示词

—

--resolution <res>

分辨率（如 1280*720）

—

--ratio <ratio>

宽高比（如 16:9, 1:1）

—

--duration <seconds>

视频时长（秒）

5

--prompt-extend <bool>

是否启用提示词扩展

—

--watermark <bool>

是否添加水印

true

--seed <n>

随机种子

—

--download <path>

完成后保存到文件

—

--async

立即返回任务 ID（异步模式，适用于 Agent/CI）

—

--poll-interval <seconds>

轮询间隔

5

bl video edit 编辑视频，支持风格转换、对象替换等。 
bl video edit --video <url> --prompt <text> [flags]

参数

说明

默认值

--video <url>

输入视频 URL 或本地文件（2-10 秒）

—

--prompt <text>

编辑指令

—

--model <model>

模型 ID

happyhorse-1.0-video-edit

--ref-image <url>

参考图片（最多 4 张，逗号分隔）

—

--negative-prompt <text>

反向提示词

—

--resolution <res>

分辨率：720P 或 1080P

1080P

--ratio <ratio>

宽高比（16:9, 9:16, 1:1, 4:3, 3:4）

—

--duration <seconds>

输出时长（2-10 秒）

—

--audio-setting <mode>

音频处理：auto 或 origin（保留原声）

auto

--prompt-extend <bool>

是否启用提示词扩展

—

--watermark <bool>

是否添加水印

true

--seed <n>

随机种子

—

--download <path>

保存到文件

—

--no-wait

立即返回任务 ID

—

--poll-interval <seconds>

轮询间隔

15

bl video ref 多图参考生成视频，支持多主体、多镜头、配音。 
bl video ref --prompt <text> --image <url>... [flags]

参数

说明

默认值

--prompt <text>

视频描述，使用标记引用素材（图1、视频1 等）

—

--model <model>

模型 ID

happyhorse-1.1-r2v

--image <url>

参考图片（可重复，用于多主体）

—

--ref-video <url>

参考视频（可重复）

—

--image-voice <url>

图片对应的配音（按位置配对）

—

--video-voice <url>

视频对应的配音（按位置配对）

—

--resolution <res>

分辨率：720P 或 1080P

720P

--ratio <ratio>

宽高比（16:9, 9:16, 1:1）

—

--duration <seconds>

视频时长（2-10 秒）

5

--prompt-extend <bool>

是否启用提示词扩展

—

--watermark <bool>

是否添加水印

true

--seed <n>

随机种子

—

--download <path>

保存到文件

—

--no-wait

立即返回任务 ID

—

--poll-interval <seconds>

轮询间隔

15

bl video task get 查询异步视频任务的状态。 
bl video task get --task-id <id>

参数

说明

--task-id <id>

异步任务 ID

bl video download 按任务 ID 下载已完成的视频。 
bl video download --task-id <id> --out <path>

参数

说明

--task-id <id>

任务 ID

--out <path>

输出文件路径

视觉理解

bl vision describe 使用视觉模型描述图片或视频内容。 
bl vision describe --image <path-or-url> [flags]

参数

说明

默认值

--image <path-or-url>

图片路径或 URL

—

--video <url>

视频文件路径或 URL

—

--prompt <text>

关于内容的问题

自动检测

--model <model>

视觉模型

qwen3-vl-plus

语音合成与识别

bl speech synthesize 文字转语音（TTS）。 
bl speech synthesize --text <text> [flags]

参数

说明

默认值

--text <text>

要合成的文本

—

--text-file <path>

从文件读取文本

—

--model <model>

模型 ID

cosyvoice-v3-flash

--voice <voice>

音色 ID（用 --list-voices 查看）

—

--list-voices

列出可用音色

—

--format <format>

音频格式：mp3、pcm、wav、opus

mp3

--sample-rate <rate>

采样率（Hz）

—

--volume <volume>

音量（0-100）

50

--rate <rate>

语速（0.5-2.0）

1.0

--pitch <pitch>

音调（0.5-2.0）

1.0

--seed <seed>

随机种子（0-65535）

—

--language <lang>

语言提示（zh、en、ja、ko 等）

—

--instruction <text>

自然语言风格指令（如"请用温柔的语调"）

—

--enable-ssml

启用 SSML 标记解析

—

--out <path>

保存音频到文件

自动生成

--stream

流式输出原始 PCM 音频

—

bl speech recognize 语音转文字（ASR）。 
bl speech recognize --url <audio-url> [flags]

参数

说明

默认值

--url <url>

音频文件 URL 或本地路径（可重复，最多 100 个）

—

--model <model>

模型 ID

fun-asr

--language <lang>

语言提示（zh、en、ja 等）

—

--diarization

启用说话人分离

—

--speaker-count <n>

预期说话人数（需配合 --diarization）

—

--vocabulary-id <id>

热词表 ID，提高识别准确率

—

--channel-id <n>

音频通道 ID

0

--out <path>

保存完整识别结果到 JSON 文件

—

--no-wait

立即返回任务 ID

—

--poll-interval <seconds>

轮询间隔

2

联网搜索

bl search web 联网搜索。 
bl search web --query <text> [flags]

参数

说明

默认值

--query <text>

搜索关键词

—

--count <n>

搜索结果数量

10

--list-tools

列出可用的 MCP 搜索工具

—

应用与数据

bl app call 调用百炼应用（智能体或工作流）。 
bl app call --app-id <id> --prompt <text> [flags]

参数

说明

默认值

--app-id <id>

应用 ID（必填）

—

--prompt <text>

输入提示

—

--image <url>

图片 URL（可重复）

—

--file-id <id>

预上传的文件 ID（可重复）

—

--session-id <id>

会话 ID，用于多轮对话

—

--stream

流式输出（TTY 下默认开启）

—

--pipeline-ids <ids>

知识库 Pipeline ID（逗号分隔）

—

--memory-id <id>

记忆 ID，启用长期记忆

—

--biz-params <json>

业务参数 JSON（工作流变量）

—

--has-thoughts

显示 Agent 思考过程

—

bl app list 列出百炼应用。 
bl app list [flags]

参数

说明

默认值

--name <name>

按名称搜索

—

--page <n>

页码

1

--page-size <n>

每页数量

30

--region <region>

API 地域

cn-beijing

bl memory add 添加记忆。 
bl memory add --user-id <id> [flags]

参数

说明

--user-id <id>

用户 ID（必填）

--messages <json>

消息 JSON 数组

--content <text>

自定义记忆内容

--profile-schema <id>

用户画像 Schema ID

--memory-library-id <id>

记忆库 ID（隔离记忆空间）

bl memory search 搜索记忆。 
bl memory search --user-id <id> [flags]

参数

说明

默认值

--user-id <id>

用户 ID（必填）

—

--query <text>

搜索关键词

—

--messages <json>

消息 JSON 数组，用于上下文搜索

—

--top-k <n>

返回结果数量

10

--memory-library-id <id>

记忆库 ID

—

bl memory list 列出记忆。 
bl memory list --user-id <id> [flags]

参数

说明

默认值

--user-id <id>

用户 ID（必填）

—

--page-size <n>

每页数量

10

--page <n>

页码

1

--memory-library-id <id>

记忆库 ID

—

bl knowledge retrieve 从百炼知识库检索（需要 AccessKey 认证）。 
bl knowledge retrieve --index-id <id> --query <text> [flags]

参数

说明

默认值

--index-id <id>

知识库索引 ID（必填）

—

--query <text>

搜索关键词（必填）

—

--workspace-id <id>

百炼工作空间 ID

—

--top-k <n>

返回结果数量

10

--rerank

启用重排序

—

--rerank-top-n <n>

重排序后保留数量

—

--access-key-id <key>

阿里云 AccessKey ID

—

--access-key-secret <key>

阿里云 AccessKey Secret

—

开发辅助

bl file upload 上传本地文件到 DashScope 临时存储（48 小时有效）。 
bl file upload --file <path> --model <model>

参数

说明

--file <path>

本地文件路径

--model <model>

目标模型名称（文件绑定到此模型）

bl usage free 查询模型免费额度。 
bl usage free --model <model> [flags]

参数

说明

默认值

--model <model>

模型名称

—

--region <region>

API 地域

cn-beijing

bl mcp list 列出已激活的 MCP 服务。 
bl mcp list [flags]

参数

说明

默认值

--name <text>

按名称过滤

—

--type <type>

服务类型：OFFICIAL 或 PRIVATE

OFFICIAL

--page <n>

页码

1

--page-size <n>

每页数量

30

--region <region>

API 地域

cn-beijing

bl pipeline run 运行流水线工作流。 
bl pipeline run <file> [flags]

参数

说明

默认值

--input <json>

运行时输入（JSON）

—

--input-file <path>

从文件读取输入

—

--concurrency <n>

最大并行步骤数

1

--events <format>

事件输出格式：jsonl

—

--timeout <seconds>

步骤超时时间

—

bl advisor recommend 根据需求推荐最佳模型。 
bl advisor recommend <prompt> [flags]

参数

说明

--message <text>

描述您的需求

--dry-run

仅显示意图分析和候选列表，不进行排序

常见问题

Q：安装失败怎么办？ 确认 Node.js 版本 ≥ 22.12.0 且使用 npm 安装（不支持 pnpm/yarn）： 
node --version
npm install -g bailian-cli
npx skills add modelstudioai/cli --all -g
Q：提示认证失败？ 检查 API Key 是否正确配置： 
bl auth status
如需重新配置： 
bl auth logout
bl auth login --api-key sk-xxx
# 或拉起浏览器登录
bl auth login --console
Q：本地文件可以直接用吗？ 可以。直接把文件路径传给 Agent 即可，CLI 会自动上传到临时存储（48 小时有效）： 
帮我把 ./photo.png 改成水彩风格
帮我识别 ./meeting.wav 这段录音
描述一下 ./demo.mp4 这个视频的内容
Q：如何查看命令的完整参数？ 告诉 Agent “看一下 bl image generate 有哪些参数”，或直接运行： 
bl <命令> --help
阿里云百炼 home page阿里云百炼
使用 API
文本生成
图像生成
视频生成
3D模型生成
音频
实时多模态
Realtime API
  • 概述
向量与排序
更多模型
工具包/框架
模型生产
文件管理
更多