> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phanedge.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream 4.x-N 按张计费图片生成

> 通过 OpenAI 兼容接口 /v1/images/generations 使用 Doubao Seedream 4.0-N / 4.5-N 模型，按图片张数计费，适合多图采样与大图生成。

本页面向 **API 调用者**，介绍如何在 PhanEdge 中使用 **Doubao Seedream 4.0-N / 4.5-N** 模型进行图片生成，并按 **图片张数** 计费。

> 简要说明：
>
> * 模型名：`doubao-seedream-4.0-n`、`doubao-seedream-4.5-n`
> * 入口：`POST /v1/images/generations`
> * 计费：**0.2 元 / 张**（RMB），总价 ≈ `0.2 × n`

## 使用场景

与 `doubao-seedream-4.0` / `doubao-seedream-4.5` 相比，它们各自的 `*-n` 版本主要用于以下场景：

* 需要一次生成 **多张图片**（例如 `n=3`、`n=4`），按张计费更直观；
* 希望前端/客户端控制张数，并让计费与请求参数 `n` 严格对齐；

## 接口总览

### 端点

```http theme={null}
POST /v1/images/generations
```

### 请求头

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

> `TOKEN` 为 PhanEdge 幻锋AI的 API Key。

### 基础请求体

```json theme={null}
{
  "model": "doubao-seedream-4.0-n",
  "prompt": "一只可爱的海獭在海面上仰躺着，手里抱着一颗星星",
  "n": 3,
  "size": "1024x1024",
  "response_format": "url"
}
```

* `model`: 推荐使用 `doubao-seedream-4.0-n` 或 `doubao-seedream-4.5-n`；
* `prompt`: 图片描述；
* `n`: 生成图片的数量；
* `size`: 图片尺寸，支持 Seedream 的 `1K` / `2K` / `4K` 或 `宽x高`；
* `response_format`: `url`（默认）或 `b64_json`。

## 计费说明（按张计费）

在 PhanEdge 中，`doubao-seedream-4.0-n` / `doubao-seedream-4.5-n` 的计费规则为：

* **单价**：0.2 元 / 张（RMB）；
* **总价** ≈ `0.2 × 实际生成图片张数`；
* 默认情况下，图片张数与请求体中的 `n` 一致。

> 对比：
>
> * `doubao-seedream-4.0` / `doubao-seedream-4.5`：按 **每次调用** 计费，适合固定 1 张或内部控制张数的场景；
> * `doubao-seedream-4.0-n` / `doubao-seedream-4.5-n`：按 **图片张数** 计费，推荐用于多图采样、需要人工挑选最佳图片的业务。

计费在后端通过模型名与请求中的 `n` 结合计算，业务侧不需要额外处理，只需保证：

* 每次请求中明确设置 `n`；
* 对于单张图片场景，建议显式设置 `n=1`，使计费行为更可预测。

## 请求参数详情

`doubao-seedream-4.0-n` / `doubao-seedream-4.5-n` 完全兼容各自主模型（`4.0` / `4.5`）的参数集，只是在计费维度上做了区别。

常用参数：

| 参数                                               | 类型                 | 必填 | 说明                                                    |
| ------------------------------------------------ | ------------------ | -- | ----------------------------------------------------- |
| `model`                                          | string             | ✅  | 建议为 `doubao-seedream-4.0-n` 或 `doubao-seedream-4.5-n` |
| `prompt`                                         | string             | ✅  | 图片描述文本                                                |
| `n`                                              | integer            | ✅  | 生成图片数量，计费按张数计算                                        |
| `size`                                           | string             | ❌  | 图片尺寸，如 `1024x1024`、`2K`                               |
| `response_format`                                | string             | ❌  | `url` 或 `b64_json`                                    |
| `image`                                          | string / string\[] | ❌  | 参考图像 URL 或 base64，支持图生图与多图融合                          |
| `seed`                                           | integer            | ❌  | 随机数种子，支持复现                                            |
| `sequential_image_generation`                    | string             | ❌  | 组图开关：`auto` / `disabled`                              |
| `sequential_image_generation_options.max_images` | integer            | ❌  | 组图最大生成张数，范围 \[1, 15]                                  |
| `watermark`                                      | boolean            | ❌  | 是否添加水印                                                |

> 更完整的 Seedream 参数说明可参考：[图片生成总览](doubao/image)。
>
> **多图生成提示**：当你设置 `n>1` 且未显式传入 `sequential_image_generation` 时，PhanEdge 会自动启用 `auto` 并将 `max_images` 设为 `n`，以确保多图返回与计费一致。

## 使用示例

### 文生图（2K 分辨率，4.0-N）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "星际穿越，黑洞，黑洞里冲出一辆快支离破碎的复古列车，抢视觉冲击力，电影大片，末日既视感，动感，对比色，oc渲染，光线追踪，动态模糊，景深，超现实主义，深蓝，画面通过细腻的丰富的色彩层次塑造主体与场景，质感真实，暗黑风背景的光影效果营造出氛围，整体兼具艺术幻想感，夸张的广角透视效果，耀光，反射，极致的光影，强引力，吞噬",
    "size": "2K"
  }'
```

### 单图示例（n=1，4.0-N）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "一只可爱的海獭在海面上仰躺着，手里抱着一颗星星",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

### 多图采样（n=3，4.0-N）

适合需要从多个候选图中人工挑选的场景：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "三张不同角度的科幻城市夜景",
    "n": 3,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

### 图生图（I2I，4.0-N）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "将这张图片转换为水彩画风格",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

### 多图融合（4.0-N，sequential disabled）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "将图1的服装换为图2的服装",
    "image": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png"
    ],
    "sequential_image_generation": "disabled",
    "size": "2K"
  }'
```

### 组图生成（文本输入，max\_images=4）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    },
    "stream": false,
    "response_format": "url",
    "watermark": true
  }'
```

### 组图生成（单图输入，max\_images=5）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "参考这个LOGO，做一套户外运动品牌视觉设计，品牌名称为GREEN，包括包装袋、帽子、纸盒、手环、挂绳等。绿色视觉主色调，趣味、简约现代风格",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimages.png",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 5
    },
    "stream": false,
    "response_format": "url",
    "watermark": true
  }'
```

### 组图生成（多图输入，max\_images=3）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "生成3张女孩和奶牛玩偶在游乐园开心地坐过山车的图片，涵盖早晨、中午、晚上",
    "image": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png"
    ],
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 3
    },
    "size": "2K"
  }'
```

### Base64 输出（b64\_json，4.0-N）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "极简扁平风格的科技公司 logo，白底",
    "n": 1,
    "size": "512x512",
    "response_format": "b64_json"
  }'
```

返回示例（简化）：

```json theme={null}
{
  "created": 1764775347,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

### 单图示例（n=1，4.5-N）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.5-n",
    "prompt": "一只可爱的海獭在海面上仰躺着，手里抱着一颗星星",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

### 尺寸控制（像素尺寸 / 2K）

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    },
    "size": "2048x2048"
  }'
```

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0-n",
    "prompt": "生成一组共4张海报，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
        "max_images": 4
    },
    "size": "2K"
  }'
```

> 注意：`stream` 参数仅在部分配置下生效，若上游不支持流式输出，请求可能被拒绝或忽略。

## 最佳实践建议

* 建议将 `doubao-seedream-4.0-n` / `doubao-seedream-4.5-n` 专用于 **对图片张数敏感的场景**（例如：一次生成 3\~4 张、需要支付按张计费）；
* 简单只需要 1 张图的场景，可以继续使用 `doubao-seedream-4.0` / `doubao-seedream-4.5`，便于与现有逻辑对齐；
* 当你希望更精细地控制成本时，可以：
  * 在前端 UI 中将最大 `n` 限制为 4 或 6；
  * 在后台通道上为 `doubao-seedream-4.0-n` 设置单独的配额或价格策略；
  * 在业务日志中记录 `model + n`，方便后续按张数核算用量。