图片生成 - Kapon 用户文档

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

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

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

export BASE_URL="https://models.kapon.cloud/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"

统一使用：

Authorization: Bearer <TOKEN>
Content-Type: application/json

支持的模型

Seedream 5.0 Pro

模型名称：doubao-seedream-5.0-pro
版本映射：doubao-seedream-5-0-pro-260628
能力：文生图、图生图；支持 response_format="url" 或 "b64_json"。
分辨率：1K、1.5K、2K，或精确尺寸（如 2048x2048）；不要套用 Seedream 4.0 的 4K 档位。
参数限制：普通单图请求省略 n；不支持 n>1、stream=true、tools、sequential_image_generation 和 sequential_image_generation_options。

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（自动适配输入图片尺寸）。

接口说明

端点

POST /v1/images/generations

本文的 cURL 示例使用此入口。使用火山原生协议的客户端也可调用 POST /volcark/api/v3/images/generations；两种入口传入 Base64 参考图时，都需要完整的 Data URI。

请求头

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；Seedream 5.0 Pro 单图请求省略此字段，不支持 `n>1`
`response_format`	string	❌	返回格式：`url`（默认）或 `b64_json`
`quality`	string	❌	图片质量，例如 `high` / `standard`
`style`	string	❌	图片风格，例如 `vivid` / `natural`

火山方舟专用参数

参数	类型	支持模型	说明
`image`	string / string[]	Seedream 5.0 Pro / 4.5 / 4.0, SeedEdit 3.0	参考图片 URL 或完整 Data URI，不接受裸 Base64；单张可传字符串或单元素数组，多图能力及数量按模型要求
`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`

提示：所有未识别的字段会按原样提交给模型服务，但计费与用量统计只会依赖部分关键参数（如分辨率、张数等）。

Base64 参考图格式

image 中的每张参考图必须是公网可访问的图片 URL，或以下完整 Data URI：

JPEG：data:image/jpeg;base64,<完整Base64>
PNG：data:image/png;base64,<完整Base64>

MIME 类型必须与图片实际格式一致，逗号后紧接完整 Base64，不添加空格或换行。<完整Base64> 是占位符，需要替换。只传 /9j/... 或 iVBOR... 这样的裸 Base64，会被当作 URL 解析，可能返回 HTTP 400、InvalidParameter，并提示 image 的 invalid url specified。 response_format="b64_json" 只控制输出格式，不会为输入的 image 自动补前缀。

响应格式

非流式响应

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

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

Base64 响应（`response_format=b64_json`）

{
  "created": 1589478378,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

你可以在客户端将 b64_json 解码为二进制图片数据并保存成文件。 b64_json 是不带 Data URI 前缀的裸 Base64。若要将生成结果再次作为 image 输入，需要根据实际图片格式补上 data:image/jpeg;base64, 或 data:image/png;base64, 前缀。

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

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

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

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

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

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）

cURL
Python

curl -X POST "https://models.kapon.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "一只可爱的熊猫在竹林里吃竹子，阳光透过树叶洒下斑驳的光影",
    "size": "2048x2048",
    "response_format": "url"
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://models.kapon.cloud/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)

2. 组图生成（Sequential Generation）

curl -X POST "https://models.kapon.cloud/v1/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）

curl -X POST "https://models.kapon.cloud/v1/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"
  }'

3.1 Base64 图生图（Seedream 5.0 Pro）

将下面的 <完整JPEG图片Base64> 替换为 JPEG 图片的完整 Base64，保留前面的 data:image/jpeg;base64,。PNG 图片应改用 data:image/png;base64,。

curl -X POST "https://models.kapon.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "doubao-seedream-5.0-pro",
    "prompt": "将这张图片转换为水彩画风格",
    "image": [
      "data:image/jpeg;base64,<完整JPEG图片Base64>"
    ],
    "size": "2048x2048",
    "response_format": "b64_json"
  }'

成功后从 data[0].b64_json 读取并解码图片。单图也可将 image 写成一个完整 Data URI 字符串。

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

curl -X POST "https://models.kapon.cloud/v1/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. 带种子控制（可复现）

curl -X POST "https://models.kapon.cloud/v1/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）

curl -N -X POST "https://models.kapon.cloud/v1/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 5.0 Pro：可用于文生图和图生图；使用上面的专用示例，不要直接套用组图或流式参数。
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 5.0 Pro：普通生图可使用 1K、1.5K、2K，或精确尺寸（如 2048x2048）。
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. 如何去除水印？

在请求体中设置：

{
  "watermark": false
}

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

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

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

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

确认 image 字段使用的是公网可访问的 HTTPS URL，或完整 Data URI（例如 data:image/jpeg;base64,<完整Base64>）；
若出现 InvalidParameter / invalid url specified 且指向 image，先检查是否误传了裸 Base64；保留原 Base64 并补上与实际图片格式匹配的前缀；
response_format="b64_json" 是输出设置，不能代替输入图片所需的 Data URI 前缀；
若图片较大，建议预先进行压缩，避免超过上游大小限制；
对于参数名，统一使用 image 字段（数组时传入字符串数组）。

计费说明

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

​支持的模型

​Seedream 5.0 Pro

​Seedream 4.5

​Seedream 4.0

​Seedream 3.0-t2i

​SeedEdit 3.0-i2i

​接口说明

​端点

​请求头

​请求参数

​基础参数（OpenAI 兼容）

​火山方舟专用参数

​Base64 参考图格式

​响应格式

​非流式响应

​Base64 响应（response_format=b64_json）

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

​使用示例

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

​2. 组图生成（Sequential Generation）

​3. 单图生图（Seedream 4.0）

​3.1 Base64 图生图（Seedream 5.0 Pro）

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

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

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

​常见问题（FAQ）

​1. 如何选择模型？

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

​3. size 参数如何设置？

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

​5. 如何去除水印？

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

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

​计费说明

​相关链接