Seedream 生图改图文档

本文档说明如何通过 WisGate OpenAI 兼容接口调用火山引擎 Ark / Seedream 图像模型。用户侧可以使用 OpenAI Images API 兼容入口，也可以使用火山原生兼容入口。

基础信息

能力	方法	路径	说明
文生图	POST	/v1/images/generations	输入文本提示词，返回生成图片
图像编辑 / 图生图	POST	/v1/images/edits	上传参考图并输入编辑提示词
火山原生图片生成	POST	/api/v3/images/generations	尽量保留火山 Seedream 请求和响应结构

Authorization: Bearer YOUR_API_KEY

/v1/images/* 响应兼容 OpenAI Images API；/api/v3/images/generations 尽量保留火山原生请求和响应结构。

支持模型

实际可用模型以当前 WisGate 后台配置为准。常见模型名包括：

模型	用途	备注
doubao-seedream-5-0-260128	文生图、图像编辑、多参考图	Seedream 5.0 Lite
doubao-seedream-4-5-251128	文生图、图像编辑、多参考图	Seedream 4.5
doubao-seedream-4-0-250828	文生图、图像编辑、多参考图	Seedream 4

文生图

curl -X POST "https://api.wisgate.cn/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A cute baby sea otter floating on its back, soft morning light, realistic photography",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

OpenAI SDK 调用时，base_url / baseURL 使用 https://api.wisgate.cn/v1，方法使用 Images API 的生成接口。

Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.wisgate.cn/v1",
)

response = client.images.generate(
    model="doubao-seedream-5-0-260128",
    prompt="A product poster for a premium tea brand, clean layout, soft natural lighting",
    n=1,
    size="1024x1024",
)

print(response.data[0].url)

JavaScript / TypeScript SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.wisgate.cn/v1",
});

const response = await client.images.generate({
  model: "doubao-seedream-5-0-260128",
  prompt: "A cinematic product photo of a smart speaker on a wooden desk",
  n: 1,
  size: "1024x1024",
});

console.log(response.data[0]?.url);

图像编辑 / 图生图

Seedream 图像编辑对外使用 OpenAI 兼容 /v1/images/edits。请求使用 multipart/form-data，图片字段名使用 image；多图可重复传 image，也可使用 image[]。

单图编辑

curl -X POST "https://api.wisgate.cn/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=doubao-seedream-5-0-260128" \
  -F "prompt=Keep the person and pose unchanged, replace the background with a bright modern office, realistic lighting" \
  -F "image=@./input.png" \
  -F "size=1024x1024" \
  -F "response_format=url"

多参考图编辑时，可重复传 image，也可使用 image[]。

多参考图编辑

curl -X POST "https://api.wisgate.cn/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=doubao-seedream-5-0-260128" \
  -F "prompt=Combine the outfit from the first image with the studio background from the second image, realistic commercial photography" \
  -F "image[]=@./subject.png" \
  -F "image[]=@./background.png" \
  -F "size=1024x1024" \
  -F "response_format=url"

火山原生图片生成

如果调用方已经按火山 Ark 图片生成文档组织请求，可以直接请求 WisGate 的原生兼容入口：

curl -X POST "https://api.wisgate.cn/api/v3/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Generate 3 images of the same character in morning, noon, and night scenes",
    "image": [
      "https://example.com/reference-1.png",
      "https://example.com/reference-2.png"
    ],
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 3
    },
    "size": "2K",
    "output_format": "png",
    "response_format": "url",
    "watermark": false
  }'

该入口支持火山文档中的图片生成请求参数，并仍会使用 WisGate 的模型映射、渠道选择、鉴权、限流和计费逻辑。多图生成可使用 sequential_image_generation 与 sequential_image_generation_options.max_images。

原生请求参数

POST /api/v3/images/generations 使用 application/json 请求体。WisGate 会按模型映射把 model 转换为火山 Ark endpoint ID，其余 Seedream 原生参数按下表转发。

字段	类型	必填	说明
model	string	是	WisGate 模型名或火山 Ark endpoint ID。使用 WisGate 模型名时会按后台模型映射转换为上游 endpoint ID
prompt	string	是	生成或编辑提示词。批量生成多张图时，建议在提示词中明确说明要生成几张以及每张图的差异
image	string 或 string[]	否	参考图。支持公网图片 URL 或 Data URL；传入后用于图像编辑、图生图或多参考图生成
size	string	否	图片尺寸。可传 1024x1024 这类像素尺寸，也可传 Seedream 支持的 1K、2K、4K 等规格
seed	integer	否	随机种子。相同提示词和参数下用于提高结果可复现性；是否完全复现取决于具体模型
guidance_scale	number	否	提示词遵循强度。数值越高通常越贴近提示词，但可能降低画面自然度
sequential_image_generation	string	否	批量/序列生成开关，常用取值为 auto、disabled
sequential_image_generation_options	object	否	批量/序列生成配置，常用字段为 max_images
stream	boolean	否	是否启用火山原生 SSE 流式响应
output_format	string	否	输出图片格式，例如 png、jpeg、webp；是否支持取决于具体 Seedream 模型
response_format	string	否	返回图片格式，常用取值为 url、b64_json
watermark	boolean	否	是否添加 AI 生成水印；不传时使用上游默认值
optimize_prompt_options	object	否	提示词优化配置，具体字段以火山当前模型文档为准

n 不是火山原生参数。调用 /api/v3/images/generations 时如需生成多张图，请使用 sequential_image_generation 与 sequential_image_generation_options.max_images，并在 prompt 中明确多图要求。

原生 JSON 示例

文生图：

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "A cute baby sea otter floating on its back, soft morning light, realistic photography",
  "size": "1024x1024",
  "response_format": "url",
  "output_format": "png",
  "watermark": false
}

图像编辑 / 图生图：

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Keep the subject unchanged, replace the background with a bright modern office",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "response_format": "url"
}

多参考图与批量生成：

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Generate 3 images of the same character in morning, noon, and night scenes",
  "image": [
    "https://example.com/reference-1.png",
    "https://example.com/reference-2.png"
  ],
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 3
  },
  "size": "2K",
  "response_format": "url",
  "output_format": "png"
}

OpenAI 兼容字段

字段	类型	必填	说明
model	string	是	WisGate 模型名，由服务方提供
prompt	string	是	图像生成或编辑提示词
n	integer	否	期望生成图片数量。Seedream 下仍建议在提示词中明确要生成几张图
size	string	否	图片尺寸。可传 1024x1024，也可传 Seedream 支持的 1K、2K、4K
response_format	string	否	url 或 b64_json，默认建议使用 url
output_format	string	否	输出图片格式，如 png、jpeg、webp，是否生效取决于具体模型
watermark	boolean	否	是否添加 AI 生成水印；不传时使用火山默认值

Seedream 扩展字段

以下字段可在 JSON 请求体顶层传入，WisGate 会转发给火山上游：

字段	类型	说明
image	string 或 string[]	参考图 URL 或 Data URL
seed	integer	随机种子。是否生效取决于具体模型
guidance_scale	number	提示词遵循强度。是否生效取决于具体模型
sequential_image_generation	string	auto 或 disabled
sequential_image_generation_options	object	批量生成配置，例如 {"max_images": 3}
stream	boolean	是否启用火山原生 SSE 流式图片输出
optimize_prompt_options	object	提示词优化配置，例如 {"mode": "fast"}

示例：

curl -X POST "https://api.wisgate.cn/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Generate three related scenes of the same character: morning, afternoon, and night",
    "size": "2K",
    "response_format": "url",
    "output_format": "png",
    "watermark": false,
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 3
    }
  }'

n 与批量生成

用户请求	上游转换
n 为空或小于等于 1	不额外设置批量生成参数
n 大于 1	默认设置 sequential_image_generation: "auto" 和 sequential_image_generation_options.max_images: n
用户显式传入批量生成字段	以用户显式字段为准

如果需要严格控制批量生成行为，建议直接传 Seedream 扩展字段，并在提示词中明确说明要生成几张图以及每张图的差异。

响应格式

成功响应示例：

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1770000000,
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "size": "1024x1024"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}

字段	说明
data[].url	图片 URL。火山返回的链接通常有有效期，建议业务侧及时下载或转存
data[].b64_json	当 response_format=b64_json 时返回 Base64 图片内容
data[].size	火山返回的实际图片尺寸
usage.generated_images	成功生成的图片数量
usage.output_tokens / usage.total_tokens	火山上游返回的图片 token 消耗

计费说明

Seedream 支持按 token 或按次计费，具体取决于后台 model_details 中该模型的价格配置。

配置方式	计费行为
pricing_mode=per-token	使用上游 usage.output_tokens / usage.total_tokens 映射后的 token 用量计费
pricing_mode=per-request	使用单次 model_price 计费，并乘以 usage.generated_images

当 pricing_mode=per-request 时，如果火山返回：

{
  "usage": {
    "generated_images": 3
  }
}

最终按 model_price * 3 * group_ratio 结算。若上游没有返回 usage.generated_images，则按 1 次请求结算。

流式响应

stream=true 时，WisGate 会转发火山原生 SSE 事件流，Content-Type 为 text/event-stream。客户端应按火山原生事件结构处理 partial_succeeded、completed 和错误事件。

event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream","created":1770000000,"image_index":0,"url":"https://example.com/1.png","size":"1024x1024"}

event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream","created":1770000001,"usage":{"generated_images":1,"output_tokens":4096,"total_tokens":4096}}

WisGate 会从流式事件中的 usage 解析消耗用于计费。

常见问题

场景	处理建议
401 或鉴权失败	检查火山渠道 API Key 以及用户侧 Authorization: Bearer YOUR_API_KEY
model is required	请求体或 multipart 表单必须包含 model
图片编辑提示 image is required	/v1/images/edits 必须上传 image、image[] 或 image[n] 字段
尺寸不支持	检查目标 Seedream 模型官方支持的 size 范围
图片 URL 过期	火山返回的 URL 有有效期，业务侧应及时下载或转存