# 快速入门(新手版)
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本教程专为**零基础用户**设计，无需安装任何编程环境（如 Python），直接使用操作系统内置工具即可体验方舟大模型服务。
## 1. 准备工作
在开始之前，请确保您已经完成以下准备：
1. **注册账号**：确保您拥有火山引擎账号并已 [登录](https://console.volcengine.com/)。
2. **获取 API Key**：
* 访问 [API Key 管理页面](https://ark.volcengine.com/region:cn-beijing/apikey)。
* 点击“创建 API Key”，并复制保存您的 Key。
> **注意**
>
> 请妥善保管您的 API Key，不要泄露给他人。
> 当前脚本兼容历史 UUID 格式以及新格式 `ark--` 的 Key。
3. **开通模型（可选）**：所有新用户可使用免费额度体验模型服务。如额度使用完毕需要 [开通模型](https://ark.volcengine.com/region:cn-beijing/openManagement)，以继续使用方舟模型服务。
> **注意**
>
> 开通 Seedance 2.0 模型，需要保证账户余额超过 200元或者购买资源包，详细请参见[Doubao Seedance 2.0 系列教程](/docs/seedance-2-0)。
4. 下载并解压文件：点击下载下方附件，将其解压到您的本地目录（如桌面或"下载"文件夹）。
[ark_quickstart_package.zip](https://arkdocs.tos-cn-beijing.volces.com/files/tutorials/ark_quickstart_package_arkruntime-20260909.zip)
## 2. 一键体验模型服务（零门槛）
打开我们为您准备的文件。请根据您的操作系统选择对应的操作。
### Windows 用户
**适用系统**：Windows 7 SP1 及以上（推荐 Windows 10/11）
1. 找到项目文件夹中的 `scripts/zero_dependency/windows` 目录。
2. 双击运行 **`run_windows.bat`** 文件。
> 提示：如果这是您第一次运行，可能会弹出权限询问窗口，请输入 `Y` 或允许运行。
3. 脚本会自动启动 PowerShell 环境。
4. 根据提示输入您的 **API Key** 并回车。
5. 稍等片刻，您将看到 AI 的回复内容。
### macOS 用户
**适用系统**：macOS 10.15及以上版本
1. 找到项目文件夹中的 `scripts/zero_dependency/mac` 目录。
2. 双击运行 **`quickstart.sh`** 文件。
> 提示：如果系统提示“无法打开，因为它来自未验证的开发者”
> 1. 按住 `Control` 键点击文件，选择“打开”，然后在弹出的对话框中再次点击“打开”。
> 2. 如果还是无法打开，直接在终端窗口运行脚本。可以打开终端（terminal），将 quickstart.sh 拖入窗口，回车运行。
3. 终端窗口会自动打开。
4. 根据提示输入您的 **API Key** 并回车。
5. 等待片刻，您将看到 AI 的回复内容。
### 运行说明
当您看到“调用成功”时，说明您已经完成了第一次 API 调用。
脚本自动完成了以下步骤：
1. **构造请求**：按照方舟平台的规范，打包了一段问候语：“你好！请用一句话介绍一下你自己。”
2. **发送请求**：使用系统自带的网络工具（Windows 的 PowerShell 或 Mac 的 Curl）向方舟服务器发送消息。
3. **解析回复**：自动处理服务器返回的数据，并提取出 AI 生成的文本展示给您。
## 3. 一键搭建开发环境
如果您已经成功体验了 API 调用，并希望开始真正的 Python 编程开发，但又不想被复杂的环境配置（Python 版本、pip、虚拟环境）所困扰，请尝试我们的**自动化环境构建工具**。
我们将使用轻量、快速的现代化 Python 包管理器 `uv`（无需预安装Python即可使用），为您在项目内部自动下载并配置一个隔离的、纯净的、标准的 Python 开发环境，完全不会干扰您系统中已有的Python配置。
### Windows 用户
1. 进入 `scripts/init_dev_env` 目录。
2. 双击运行 **`setup_windows.bat`**。
3. 脚本会自动执行以下操作：
* 下载 `uv` 工具。
* 自动下载 Python 3.12（如果不干扰您的系统 Python）。
* 创建虚拟环境 `.venv`。
* 安装方舟 SDK。
4. 完成后，在项目根目录会生成一个 `run_demo.bat`。
5. 双击 `run_demo.bat`，即可运行标准的 Python SDK 示例代码 (`python/``demo_standard.py`)。
6. 如果您希望按需生成 Python 示例脚本，可运行：
```Bash
.venv/bin/python python/gen_example.py
```
Windows 用户请运行：
```Bash
.venv\Scripts\python python/gen_example.py
```
生成器支持多选示例类型、修改默认 Model ID，并可在缺少 `ARK_API_KEY` 时提示输入并选择写入项目根目录 `.env`。
### macOS 用户
1. 打开终端，进入 `scripts/init_dev_env` 目录。
2. 运行构建脚本：
```Bash
./setup_mac.sh
```
3. 脚本会自动配置好所有环境。
4. 完成后，在项目根目录会生成一个 `run_demo.sh`。
5. 运行 `./run_demo.sh` 即可体验标准开发流程。
6. 如果您希望按需生成 Python 示例脚本，可运行：
```Bash
.venv/bin/python python/gen_example.py
```
生成器支持多选示例类型、修改默认 Model ID，并可在缺少 `ARK_API_KEY` 时提示输入并选择写入项目根目录 `.env`。
### 运行说明
当您运行 `setup_windows.bat` 或 `setup_mac.sh` 后，您的项目文件夹中多了一个 `.venv` 文件夹。
这是一个**虚拟环境 (Virtual Environment)**。它包含了 Python 解释器和方舟 SDK。
* **优势**：无论您系统里安装了何种 Python 版本，该目录下的环境始终是纯净、稳定、可用的。
* **后续建议**：您可以下载 [TRAE](https://www.trae.ai/) 编程工具，打开本项目文件夹，自动识别到该虚拟环境，您即可像专业工程师一样开始编写代码。
> **说明**
>
> 推荐安装方舟文档 MCP，结合支持 MCP 的 Agent 或代码开发工具，可智能完成方舟代码开发与调试。
> 主流编程工具支持一键安装，OpenClaw 等智能体一句话即可安装，详见[方舟文档 MCP](/docs/tutorials-mcp)。
## 4. 常见问题
**Q: 双击** **`run_windows.bat`** **后窗口一闪而过怎么办？**
A: 请尝试右键点击 `run_windows.bat`，选择“以管理员身份运行”。或者先打开 CMD 命令行，拖入 `run_windows.bat` 文件运行，查看具体报错信息。
**Q: Mac 提示“Permission denied”？**
A: 请打开终端，输入 `chmod +x `（注意最后有个空格），然后将 `run_mac.command` 文件拖入终端，按回车。这会赋予文件运行权限。
**Q: 报错“API Key 无效”？**
A: 请检查您输入的 Key 是否完整，是否包含多余的空格。建议直接从控制台复制粘贴。
## 5. 下一步
您已经成功迈出了第一步！接下来，您可以：
* **继续体验更多能力**：重新运行脚本，在能力菜单中切换到图片生成、视频生成、多模态向量化或工具调用。
* **修改 Prompt**：脚本运行时会直接展示默认 Prompt，您无需编辑源码文件即可替换成自己的输入。
* **配置环境变量**：建议先配置 `ARK_API_KEY`，这样后续运行脚本时无需重复输入密钥。
* **学习更多**：查看标准版 [快速入门](/docs/quick-start) 查看更多示例代码和进阶用法。
* **浏览模型**：访问 [模型广场](https://ark.volcengine.com/region:cn-beijing/model) 查看更多可用的强大模型。