# 火山方舟接入教程：用豆包 Seedream 生成图片

DSH Ark Toolkit 的在线能力全部走字节火山方舟（Volcengine Ark）：

- **文生图**（`ark_generate_image` 工具）：OpenAI 兼容 `/images/generations`，默认模型 `doubao-seedream-5-0-flash-260915`（Seedream 5.0 flash），别名只保留 `seedream-5.0-flash` 与 `seedream-5.0-pro`。
- **语音合成**（`ark_speak` 工具）：独立的火山引擎语音技术服务，见 [安装与配置指南](installation.md) 的 TTS 章节。

> 图片**理解**不需要本插件：DeepSeek Harness 里的 DeepSeek 模型已经原生支持图片输入，直接把图片交给模型即可。

本教程说明如何申请火山方舟 API Key、在 Ark Toolkit 中配置，并给出可直接运行的 cURL 示例。

## 1. 注册火山引擎并开通方舟

1. 打开 [火山引擎控制台](https://console.volcengine.com/ark)，用手机号或账号登录。没有账号先注册并完成实名认证。
2. 进入 **火山方舟（Ark）** 控制台。首次使用需要开通服务；部分模型需要先在 **模型广场** 领取/开通（如 Seedream 系列）。
3. 在左侧 **API Key 管理** 点击 **创建 API Key**，复制生成的 Key（形如 `xxxxxxxx-xxxx-...`）。请妥善保存，只在配置时使用一次。

> 提示：火山方舟按量计费，部分新模型有免费试用额度；具体价格与免费额度以控制台为准。

## 2. 在 Ark Toolkit 中配置

打开 **插件 → 已安装 → 火山引擎方舟工具包** 的详情页，默认值已经指向火山方舟：

| 字段 | 值 |
| --- | --- |
| Base URL | `https://ark.cn-beijing.volces.com/api/v3` |
| 默认 Seedream 模型 | `doubao-seedream-5-0-flash-260915` |
| API Key | 你的火山方舟 Key |

在 **API 密钥** 里粘贴刚才创建的 Key，点击 **保存设置**。插件会把 Key 保存为 DSH Credential（默认名 `ARK_API_KEY`），随后可以运行 **测试 API 连接** 确认可达性。

也可以在 Profile patch 中配置：

```yaml
- id: ark-toolkit
  config:
    provider:
      baseUrl: https://ark.cn-beijing.volces.com/api/v3
      credential: ARK_API_KEY
```

## 3. 直接调用

### 文生图（Seedream）

```bash
curl https://ark.cn-beijing.volces.com/api/v3/images/generations \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-flash-260915",
    "prompt": "一只在雪地里打滚的橘猫，高清摄影",
    "size": "2K",
    "output_format": "png",
    "watermark": false
  }'
```

Seedream 5.0 pro / flash 的 `size` 只有两种写法（不可混用）：

| 写法 | 取值 | 说明 |
| --- | --- | --- |
| 分辨率档位 | `1K`、`1.5K`、`2K`（默认 2K） | 官方推荐；1.5K 与 1K 同价、效果更好 |
| 宽高像素 | `<宽>x<高>`，如 `2048x1024` | 总像素须落在 `921600`~`4624220`，宽高比须落在 `1/16`~`16` |

**没有 `aspect_ratio` 参数**：指定宽高比的官方做法是把宽高比写进提示词（档位写法），或直接传上表第二行的像素值。Ark Toolkit 的 `aspectRatio` 参数会在内部按官方像素表换算成像素值，例如 `size=2K` + `aspectRatio=16:9` 实际发送 `"size": "2816x1584"`：

```bash
curl https://ark.cn-beijing.volces.com/api/v3/images/generations \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "A mountain landscape at sunset",
    "size": "2816x1584",
    "output_format": "png",
    "watermark": false
  }'
```

其他值得注意的参数（两款模型一致）：`response_format`（`url` 默认 / `b64_json`）、`output_format`（`png` / `jpeg`，接口默认 `jpeg`）、`background`（`opaque` 默认 / `transparent`，仅图生图且输入 1 张带透明通道图）、`watermark`（默认 `true`）、`layer_decomposition`（图层拆分）。`sequential_image_generation`（组图）、`stream`（流式）与联网工具**不支持** 5.0 pro / flash。

## 常见问题

| 问题 | 处理方式 |
| --- | --- |
| `401` / Key 无效 | 检查 Key 是否复制完整、有没有多余空格；到控制台 **API Key 管理** 重新创建 |
| 模型不存在或未开通 | 到火山方舟 **模型广场** 开通对应模型（Seedream 系列）；不同模型 ID 见控制台 |
| 提示余额不足 | 在火山引擎控制台充值或领取免费额度 |
| `429` 限流 | 按错误信息等待后重试，或在控制台提升配额 |
| 想换 Seedream 版本 | 调用 `ark_generate_image` 时传 `model` 参数：别名有 `seedream-5.0-flash`（默认）/ `seedream-5.0-pro`；其它版本传完整 Ark 模型 ID。注意 `doubao-seedream-5-0-lite-260128` 与 `doubao-seedream-4-5-251128` 已列入方舟第十批下线（EOM 2026-09-24、**EOS 2026-11-24 14:00 UTC+8**），`doubao-seedream-4-0-250828` 同样在列 |