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

# 图片生成

> 通过 OpenAI 兼容接口使用火山方舟 Seedream 图片生成模型，支持文生图、图生图、组图等功能。

本页介绍如何在 HingNet AI 中，通过 **OpenAI 兼容接口** `/v1/images/generations` 调用 Doubao Seedream 图片生成模型，包括：

* 文生图（Text-to-Image，T2I） 🖼️
* 图生图（Image-to-Image，I2I） 🎨
* 多图融合与组图生成 ✨
* 流式输出（SSE） 🔄

所有请求都经由 HingNet AI 转发到火山方舟，**不需要自行签名**，只需在 Header 中携带 HingNet AI API Key。

```bash theme={null}
export BASE_URL="https://models.hingnet.com.cn/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

统一使用：

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

## 支持的模型

### Seedream 4.5

* **模型名称**：`doubao-seedream-4.5`
* **计费别名**：`doubao-seedream-4.5-n`（按图片张数计费）
* **版本映射**：`doubao-seedream-4-5-251128`
* **能力**：与 Seedream 4.0 基本一致（以官方控制台为准）

### Seedream 4.0

* **模型名称**：`doubao-seedream-4.0`
* **计费别名**：`doubao-seedream-4.0-n`（按图片张数计费，单张 0.2 元；适合需要通过 `n` 一次生成多张图片的场景）
* **版本映射**：`doubao-seedream-4-0-250828`
* **能力**：
  * ✅ 文生图（Text-to-Image）
  * ✅ 单图生图（Image-to-Image）
  * ✅ 多图融合（2-10 张输入）
  * ✅ 组图生成（Sequential Generation，最多 15 张）
  * ✅ 流式输出（SSE）
  * ✅ 提示词优化（标准 / 快速模式）
  * ✅ 水印控制
* **分辨率**：
  * 支持 `1K`、`2K`、`4K` 分辨率模式
  * 支持精确尺寸（如 `2048x2048`）
  * 总像素范围：\[921,600, 16,777,216]
  * 宽高比范围：\[1/16, 16]

### Seedream 3.0-t2i

* **模型名称**：`doubao-seedream-3.0-t2i`
* **版本映射**：`doubao-seedream-3-0-t2i-250415`
* **能力**：
  * ✅ 文生图（Text-to-Image）
  * ✅ seed 控制（随机数种子）
  * ✅ guidance\_scale 控制（文本权重）
* **分辨率**：
  * 总像素范围约在 `512x512` 到 `2048x2048` 之间（以火山官方文档为准）。

### SeedEdit 3.0-i2i

* **模型名称**：`doubao-seededit-3.0-i2i`
* **版本映射**：`doubao-seededit-3-0-i2i-250628`
* **能力**：
  * ✅ 图生图（Image-to-Image）
  * ✅ seed 控制
  * ✅ guidance\_scale 控制
* **分辨率**：
  * 推荐使用 `adaptive`（自动适配输入图片尺寸）。

## 接口说明

### 端点

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

### 请求头

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

控制台侧需要将 `doubao-seedream-*` / `doubao-seededit-*` 模型名绑定到 Doubao / VolcArk 渠道（`ChannelTypeVolcArk`），即可通过统一的 OpenAI 风格接口访问。

## 请求参数

### 基础参数（OpenAI 兼容）

| 参数                | 类型      | 必填 | 说明                            |
| ----------------- | ------- | -- | ----------------------------- |
| `model`           | string  | ✅  | 模型名称，如 `doubao-seedream-4.0`  |
| `prompt`          | string  | ✅  | 图片描述文本，建议不超过 300 汉字或 600 英文单词 |
| `size`            | string  | ❌  | 图片尺寸，如 `1024x1024`、`2K`       |
| `n`               | integer | ❌  | 生成图片数量（非组图模式），默认 1            |
| `response_format` | string  | ❌  | 返回格式：`url`（默认）或 `b64_json`    |
| `quality`         | string  | ❌  | 图片质量，例如 `high` / `standard`   |
| `style`           | string  | ❌  | 图片风格，例如 `vivid` / `natural`   |

### 火山方舟专用参数

| 参数                                               | 类型                 | 支持模型                       | 说明                                    |
| ------------------------------------------------ | ------------------ | -------------------------- | ------------------------------------- |
| `image`                                          | string / string\[] | Seedream 4.0, SeedEdit 3.0 | 参考图片（URL 或 base64），支持单图或多图（2-10 张）    |
| `seed`                                           | integer            | Seedream 3.0, SeedEdit 3.0 | 随机数种子，范围通常为 \[-1, 2147483647]，-1 表示随机 |
| `sequential_image_generation`                    | string             | Seedream 4.0               | 组图功能：`auto`（自动判断）或 `disabled`（关闭）     |
| `sequential_image_generation_options`            | object             | Seedream 4.0               | 组图配置对象                                |
| `sequential_image_generation_options.max_images` | integer            | Seedream 4.0               | 最多生成图片数量，范围 \[1, 15]                  |
| `stream`                                         | boolean            | Seedream 4.0               | 是否启用流式输出（SSE）                         |
| `guidance_scale`                                 | float              | Seedream 3.0, SeedEdit 3.0 | 文本权重，范围一般为 \[1, 10]，值越大与提示词越相关        |
| `watermark`                                      | boolean            | 全部                         | 是否添加水印，默认 `true`                      |
| `optimize_prompt_options`                        | object             | Seedream 4.0               | 提示词优化配置                               |
| `optimize_prompt_options.mode`                   | string             | Seedream 4.0               | 优化模式：`standard`（默认）或 `fast`           |

> 提示：所有未识别的字段会按原样透传给火山方舟上游，但计费与用量统计只会依赖部分关键参数（如分辨率、张数等）。

## 响应格式

### 非流式响应

标准的 OpenAI 图片响应形态如下：

```json theme={null}
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

### Base64 响应（`response_format=b64_json`）

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

你可以在客户端将 `b64_json` 解码为二进制图片数据并保存成文件。

## 流式响应（Seedream 4.0，`stream=true`）

Seedream 4.0 支持通过 **服务器端事件（SSE）** 按增量返回图片生成进度，适用于组图和大图生成场景。

典型事件类型：

1. `image_generation.partial_succeeded` - 某张图片生成成功；
2. `image_generation.partial_failed` - 某张图片生成失败；
3. `image_generation.completed` - 所有图片处理完毕。

示例事件（仅示意，实际字段以火山官方文档为准）：

```text theme={null}
data: {"type":"image_generation.partial_succeeded","model":"doubao-seedream-4.0","image_index":0,"url":"https://...","size":"2048x2048"}
```

```text theme={null}
data: {"type":"image_generation.completed","usage":{"generated_images":2,"output_tokens":32768,"total_tokens":32768}}
```

在命令行中，建议使用 `curl -N` 关闭缓冲；在 Python 中可以使用 `requests.post(..., stream=True)` 或 OpenAI SDK 的流式接口逐行消费事件。

## 使用示例

### 1. 基础文生图（Seedream 4.0）

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "$BASE_URL/images/generations" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedream-4.0",
        "prompt": "一只可爱的熊猫在竹林里吃竹子，阳光透过树叶洒下斑驳的光影",
        "size": "2048x2048",
        "response_format": "url"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://models.hingnet.com.cn/v1",
        api_key="oh-xxxxxxxx"
    )

    response = client.images.generate(
        model="doubao-seedream-4.0",
        prompt="一只可爱的熊猫在竹林里吃竹子，阳光透过树叶洒下斑驳的光影",
        size="2048x2048",
        response_format="url"
    )

    print(response.data[0].url)
    ```
  </Tab>
</Tabs>

### 2. 组图生成（Sequential Generation）

```bash theme={null}
curl -X POST "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "四季变换的风景，春夏秋冬",
    "size": "1024x1024",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    }
  }'
```

### 3. 单图生图（Seedream 4.0）

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

### 4. 多图融合（2-10 张输入）

```bash theme={null}
curl -X POST "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "融合这些图片的风格元素",
    "image": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ],
    "size": "2048x2048"
  }'
```

### 5. 带种子控制（可复现）

```bash theme={null}
curl -X POST "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-3.0-t2i",
    "prompt": "梵高风格的星空",
    "size": "1024x1024",
    "seed": 12345,
    "guidance_scale": 7.5
  }'
```

### 6. 流式组图（Seedream 4.0 + SSE）

```bash theme={null}
curl -N -X POST "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "一组夕阳下的城市天际线，不同视角的构图",
    "size": "1024x1024",
    "stream": true,
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    }
  }'
```

## 常见问题（FAQ）

### 1. 如何选择模型？

* **Seedream 4.0**：最新版本，功能最全，支持组图、流式、多图融合，推荐默认使用。
* **Seedream 3.0-t2i**：仅文生图，但支持 `seed` 和 `guidance_scale` 精细控制。
* **SeedEdit 3.0-i2i**：专门用于图生图编辑场景。

### 2. 组图和 `n` 参数的区别？

* **组图**（`sequential_image_generation=auto`）：生成一组**内容相关**的图片，由模型根据理解自动决定数量（受 `max_images` 限制）。
* **`n` 参数**：生成 `n` 张**相对独立**的图片，通常只用于简单多张采样场景。

### 3. `size` 参数如何设置？

* **Seedream 4.0**：
  * 分辨率模式：`1K`、`2K`、`4K`（在 prompt 中描述宽高比）；
  * 精确尺寸：如 `2048x2048`（总像素需在 921,600 - 16,777,216 之间）。
* **Seedream 3.0-t2i**：推荐在 `512x512` 到 `2048x2048` 范围内选择。
* **SeedEdit 3.0-i2i**：建议使用 `adaptive`，由模型根据输入图自动调整。

### 4. 图片 URL 有效期多久？

生成的图片 URL 通常在 **24 小时内有效**，请在有效期内完成下载并保存到自己的存储。

### 5. 如何去除水印？

在请求体中设置：

```json theme={null}
{
  "watermark": false
}
```

即可关闭模型水印（前提是当前模型与账号配置允许关闭）。

### 6. 流式输出有什么好处？

* 实时查看每张图片的生成进度；
* 组图场景下，某张图失败不影响其他图片；
* 适合需要即时反馈的前端应用（如绘画直播、交互式创作）。

### 7. 图生图时图片传不上去怎么办？

* 确认 `image` 字段使用的是公网可访问的 HTTPS URL，或正确的 base64 字符串；
* 若图片较大，建议预先进行压缩，避免超过上游大小限制；
* 对于参数名，统一使用 `image` 字段（数组时传入字符串数组）。

## 计费说明

* 按 **成功生成的图片张数** 计费；
* 生成失败的图片通常不计费（以上游账单为准）；
* 具体价格请在后台 **模型价格管理** 中查看 Doubao Seedream 相关条目。

## 相关链接

* 🔗 [火山方舟官方文档（Seedream）](https://www.volcengine.com/docs/82379/1666945)
* 🔗 [Seedream 4.0 提示词指南](https://www.volcengine.com/docs/82379/1829186)
* 🔗 [Seedream 3.0 提示词指南](https://www.volcengine.com/docs/82379/1795150)