图像生成接口文档

文档版本: v1.0.0
接口状态: 正式发布 (General Availability)
适用范围: 数眼智能AI开放平台 · 图像生成服务

1. 概述

doubao-seedream-5-0-260128 是基于字节跳动豆包 Seedream 5.0 大模型的高品质文生图服务，通过 OpenAI 兼容的 /v1/images/generations 统一接口提供调用。该模型支持中英文提示词输入，原生输出高分辨率图像（最高支持 4096x4096），适用于营销素材生成、创意设计、电商场景等多种业务场景。

1.1 核心能力

能力	说明
文本生成图像	根据自然语言描述生成高质量图像
多语言提示词	支持中文、英文等多语言输入
灵活分辨率	支持正方形、横版、竖版等多种画幅比例
超高分辨率	原生支持最高 4096x4096 输出（总像素上限 16,777,216）
多种返回格式	支持临时 URL 或 Base64 编码两种输出方式

2. 鉴权方式

所有请求必须通过 HTTP Authorization 请求头携带 API Key 进行身份认证。

Authorization: Bearer {your_api_key}

项目	说明
认证方式	Bearer Token
令牌获取	登录平台控制台，在「令牌管理」页面创建
传输协议	HTTPS（强制）

安全提示: API Key 是您的身份凭证，请妥善保管，切勿在客户端代码、公开仓库或日志中暴露。

3. 接口定义

3.1 基本信息

项目	值
请求地址	`https://platform.shuyanai.com/v1/images/generations`
请求方法	`POST`
Content-Type	`application/json`
响应格式	`application/json; charset=utf-8`

3.2 请求参数

请求体 (Request Body)

参数名	类型	必填	默认值	说明
`model`	string	是	—	模型标识符，固定为 `doubao-seedream-5-0-260128`
`prompt`	string	是	—	图像描述提示词，支持中文和英文，不可为空
`size`	string	否	`2048x2048`	输出图像尺寸，格式为 `{width}x{height}`，详见 3.3 尺寸规格
`n`	integer	否	`1`	生成图像数量。当前该模型固定返回 1 张图像
`response_format`	string	否	`url`	返回格式：`url`（临时下载链接）或 `b64_json`（Base64 编码）

提示词建议: 描述越具体、结构化越好。建议包含：主体对象、场景环境、风格/画风、光照氛围、画面构图等要素。

关于 quality 和 style 参数: 本接口兼容 OpenAI 的 quality 和 style 参数，传入不会报错。从 OpenAI SDK 迁移时无需移除这些参数。

请求示例

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "一只可爱的熊猫在翠绿的竹林中悠闲地吃竹子，水墨画风格，细节丰富",
  "size": "2048x2048",
  "n": 1,
  "response_format": "url"
}

3.3 尺寸规格

该模型要求输出图像的总像素数不低于 3,686,400 像素（即 1920 x 1920），且不超过 16,777,216 像素（即 4096 x 4096）。宽度和高度可自由组合，无需固定为预设值。

尺寸	画幅比例	总像素	适用场景
`1920x1920`	1:1	3,686,400	社交媒体头像、封面（最小合规尺寸）
`2048x2048`	1:1	4,194,304	通用正方形，兼顾质量与成本
`2560x1440`	16:9	3,686,400	横版海报、桌面壁纸、Banner
`1440x2560`	9:16	3,686,400	竖版海报、手机壁纸、短视频封面
`3840x2160`	16:9	8,294,400	4K 超高清横版，高端印刷品
`2160x3840`	9:16	8,294,400	4K 超高清竖版，大幅展示
`4096x4096`	1:1	16,777,216	最大尺寸，超高清正方形

3.4 响应结构

成功响应 (HTTP 200)

字段	类型	说明
`model`	string	使用的模型标识符
`created`	integer	响应创建的 Unix 时间戳（秒）
`data`	array	生成结果数组
`data[].url`	string	图像临时下载链接（`response_format` 为 `url` 时返回）
`data[].b64_json`	string	图像 Base64 编码数据（`response_format` 为 `b64_json` 时返回）
`data[].size`	string	实际生成图像的尺寸
`usage`	object	用量统计
`usage.generated_images`	integer	本次生成的图像数量
`usage.output_tokens`	integer	输出消耗的 token 数
`usage.total_tokens`	integer	总消耗 token 数

成功响应示例（URL 格式）

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1781158484,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-5-0/xxx.jpeg?X-Tos-Algorithm=...&X-Tos-Expires=86400&...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

成功响应示例（Base64 格式）

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1781158519,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD/...(完整 Base64 字符串)...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

3.5 响应头

响应头	说明
`X-Oneapi-Request-Id`	平台请求 ID，用于问题排查和工单对账
`Content-Type`	`application/json; charset=utf-8`

排障建议: 遇到异常时，请记录 X-Oneapi-Request-Id 的值，提交工单时附上该 ID 可大幅加速问题定位。

4. 错误处理

4.1 错误响应结构

{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "param": "相关参数（如适用）",
    "code": "错误码"
  }
}

4.2 常见错误码

HTTP 状态码	错误码	错误类型	原因与处理方式
400	`InvalidParameter`	`upstream_error`	请求参数不合法。检查 `size` 是否满足最小像素要求（≥3,686,400），`prompt` 是否为空。
401	—	`server_error`	认证失败：`无效的令牌`。检查 API Key 是否正确，是否已过期或被禁用。
429	—	—	请求频率超限。请降低调用频率，或联系客服提升配额。
500	—	`server_error`	服务端内部错误。请稍后重试，若持续出现请提交工单。

4.3 错误响应示例

尺寸不合规:

{
  "error": {
    "message": "The parameter `size` specified in the request is not valid: image size must be at least 3686400 pixels.",
    "type": "upstream_error",
    "param": "",
    "code": "InvalidParameter"
  }
}

提示词为空:

{
  "error": {
    "message": "The parameter `prompt` specified in the request is not valid: prompt cannot be empty.",
    "type": "upstream_error",
    "param": "",
    "code": "InvalidParameter"
  }
}

认证失败:

{
  "error": {
    "code": "",
    "message": "无效的令牌",
    "type": "server_error"
  }
}

5. 调用示例

5.1 cURL

5.2 Python (requests)

5.3 Python (OpenAI SDK — 兼容模式)

5.4 Node.js (OpenAI SDK)

5.5 获取 Base64 编码图像

6. 用量与计费

6.1 Token 消耗参考计算

图像生成按输出 token 数计费，计算公式为：

output_tokens = width × height ÷ 256

尺寸	像素数	消耗 Tokens
1920x1920	3,686,400	14,400
2048x2048	4,194,304	16,384
2560x1440	3,686,400	14,400
1440x2560	3,686,400	14,400
3840x2160	8,294,400	32,400
4096x4096	16,777,216	65,536

更高分辨率意味着更高的 token 消耗，具体以响应里的 usage 字段为准。请根据实际业务场景选择合适的尺寸以优化成本。

6.2 图像 URL 有效期

当 response_format 为 url 时，返回的图像下载链接有效期为 24 小时。请在有效期内完成下载或持久化存储。超过有效期后链接将失效，需重新调用接口生成。

7. 最佳实践

7.1 提示词撰写指南

维度	建议	示例
主体描述	明确描述画面的核心对象	`一只橘色的猫` / `A red sports car`
场景环境	补充背景、场所信息	`在樱花盛开的公园中` / `on a desert highway`
风格画风	指定艺术风格或渲染方式	`水墨画风格` / `watercolor illustration`
光照氛围	描述光线和色调	`暖黄色夕阳光` / `soft natural lighting`
质量修饰	使用质量相关关键词	`高清` / `professional photography, 8K`

优质提示词示例:

A majestic snow-capped mountain range at golden hour, with a crystal-clear alpine lake
in the foreground reflecting the peaks, dramatic clouds, professional landscape photography,
ultra-detailed, 8K resolution

7.2 常见注意事项

尺寸选择: 优先使用推荐尺寸以确保最佳生图效果。自定义尺寸需满足总像素 ≥ 3,686,400 的硬性要求。

URL 及时下载: 图像 URL 有效期 24 小时，生产环境应在收到响应后立即将图像持久化到自有存储（如 OSS / S3）。

Base64 适用场景: 若下游系统不便访问外部 URL（如内网环境），可使用 b64_json 格式直接获取图像二进制数据。注意 Base64 编码会使响应体显著增大。

重试策略: 遇到 5xx 错误时建议采用指数退避重试（首次间隔 1s，最多重试 3 次）。4xx 错误无需重试，应检查请求参数。

8. 接口兼容性说明

本接口遵循 OpenAI Images API 规范，与 OpenAI 官方 SDK（Python / Node.js / Go 等）兼容。以下为与 OpenAI DALL-E 系列接口的差异对照：

参数/行为	OpenAI	本接口 (Seedream 5.0)
`size` 可选值	预设枚举（如 `1024x1024`）	自由组合，需满足 3,686,400 ~ 16,777,216 像素
`n` 参数	支持 1-10	当前固定返回 1 张
`quality` 参数	`standard` / `hd`	接受传入但不影响输出
`style` 参数	`vivid` / `natural`	接受传入但不影响输出
`response_format`	`url` / `b64_json`	`url` / `b64_json`（兼容）
返回图像格式	PNG	JPEG
`data[].size` 字段	无	返回实际生成尺寸
`usage` 字段	无	返回 token 消耗详情

9. 请求/响应完整示例

9.1 标准调用 — 2048x2048 正方形

请求:

响应:

9.2 宽屏横版 — 2560x1440 (16:9)

请求:

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "A futuristic city skyline at night with neon lights",
  "size": "2560x1440",
  "n": 1
}

响应:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1781158562,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-5-0/xxxxx.jpeg?...",
      "size": "2560x1440"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 14400,
    "total_tokens": 14400
  }
}

9.3 竖版 — 1440x2560 (9:16)

请求:

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "A portrait of a woman in traditional Chinese dress, elegant composition",
  "size": "1440x2560",
  "n": 1
}

响应:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1781158580,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-5-0/xxxxx.jpeg?...",
      "size": "1440x2560"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 14400,
    "total_tokens": 14400
  }
}

9.4 4K 超高清 — 3840x2160

请求:

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Abstract geometric art with vibrant colors and dynamic composition",
  "size": "3840x2160",
  "n": 1
}

响应:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1781158724,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-5-0/xxxxx.jpeg?...",
      "size": "3840x2160"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 32400,
    "total_tokens": 32400
  }
}

10. 变更记录

日期	版本	变更内容
2026-06-11	v1.0.0	初始发布，支持 doubao-seedream-5-0-260128 模型

11. 技术支持

如在接入或使用过程中遇到问题，请通过以下方式联系我们：

在线客服: 平台控制台右下角在线客服入口

本文档由数眼智能AI开放平台提供，最终解释权归数眼AI所有。

图像生成接口文档

1. 概述#

1.1 核心能力#

2. 鉴权方式#

3. 接口定义#

3.1 基本信息#

3.2 请求参数#

请求体 (Request Body)#

请求示例#

3.3 尺寸规格#

推荐尺寸#

3.4 响应结构#

成功响应 (HTTP 200)#

成功响应示例（URL 格式）#

成功响应示例（Base64 格式）#

3.5 响应头#

4. 错误处理#

4.1 错误响应结构#

4.2 常见错误码#

4.3 错误响应示例#

5. 调用示例#

5.1 cURL#

5.2 Python (requests)#

5.3 Python (OpenAI SDK — 兼容模式)#

5.4 Node.js (OpenAI SDK)#

5.5 获取 Base64 编码图像#

6. 用量与计费#

6.1 Token 消耗参考计算#

6.2 图像 URL 有效期#

7. 最佳实践#

7.1 提示词撰写指南#

7.2 常见注意事项#

8. 接口兼容性说明#

9. 请求/响应完整示例#

9.1 标准调用 — 2048x2048 正方形#

9.2 宽屏横版 — 2560x1440 (16:9)#

9.3 竖版 — 1440x2560 (9:16)#

9.4 4K 超高清 — 3840x2160#

10. 变更记录#

11. 技术支持#

1. 概述

1.1 核心能力

2. 鉴权方式

3. 接口定义

3.1 基本信息

3.2 请求参数

请求体 (Request Body)

请求示例

3.3 尺寸规格

推荐尺寸

3.4 响应结构

成功响应 (HTTP 200)

成功响应示例（URL 格式）

成功响应示例（Base64 格式）

3.5 响应头

4. 错误处理

4.1 错误响应结构

4.2 常见错误码

4.3 错误响应示例

5. 调用示例

5.1 cURL

5.2 Python (requests)

5.3 Python (OpenAI SDK — 兼容模式)

5.4 Node.js (OpenAI SDK)

5.5 获取 Base64 编码图像

6. 用量与计费

6.1 Token 消耗参考计算

6.2 图像 URL 有效期

7. 最佳实践

7.1 提示词撰写指南

7.2 常见注意事项

8. 接口兼容性说明

9. 请求/响应完整示例

9.1 标准调用 — 2048x2048 正方形

9.2 宽屏横版 — 2560x1440 (16:9)

9.3 竖版 — 1440x2560 (9:16)

9.4 4K 超高清 — 3840x2160

10. 变更记录

11. 技术支持