图像生成接口文档

1. 概述

图像生成通过 OpenAI 兼容的 /v1/images/generations 接口提供，可直接使用 openai SDK 调用。本文以 doubao-seedream-5-0-260128（豆包 Seedream 5.0）为主介绍，qwen-image-2.0-pro 的用法见第 8 节。

1.1 核心能力

能力	说明
文本生成图像	根据自然语言描述生成图像
多语言提示词	支持中文、英文等多语言输入
灵活分辨率	宽高可自由组合，支持正方形、横版、竖版等画幅
多种返回格式	支持临时 URL 或 Base64 编码两种输出方式

2. 鉴权方式

所有请求通过 HTTP Authorization 请求头携带 API Key：

Authorization: Bearer sk-xxx

项目	说明
认证方式	Bearer Token
令牌获取	登录控制台，在「模型 API Key」页面（`www.shuyanai.com/admin/tokens`）创建
传输协议	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 请求参数

参数名	类型	必填	默认值	说明
`model`	string	是	—	模型名，如 `doubao-seedream-5-0-260128`
`prompt`	string	是	—	图像描述提示词，支持中文和英文，不可为空
`size`	string	否	`2048x2048`	输出图像尺寸，格式为 `{宽}x{高}`，详见 3.3 尺寸规格
`n`	integer	否	`1`	生成数量。请保持为 `1`，需要多张时发起多次请求
`response_format`	string	否	`url`	返回格式：`url`（临时下载链接）或 `b64_json`（Base64 编码）

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

关于 quality 和 style 参数：传入不会报错，但不影响输出。从其他代码迁移时无需删除。

请求示例

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

3.3 尺寸规格

输出图像的总像素数（宽 × 高）需在 921,600 ～ 4,624,220 之间，宽度和高度可自由组合。超出范围时返回 400 InvalidParameter，错误信息会给出当前的上下限。

尺寸	画幅比例	总像素	适用场景
`1024x1024`	1:1	1,048,576	头像、配图
`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	竖版海报、手机壁纸、短视频封面

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	实际生成图像的尺寸
`data[].output_format`	string	图像格式，如 `jpeg`
`usage.generated_images`	integer	本次生成的图像数量
`usage.output_tokens`	integer	输出 token 数（宽 × 高 ÷ 256）
`usage.total_tokens`	integer	总 token 数

成功响应示例（URL 格式）

以下为 1024x1024 的实际响应（URL 已截断）：

{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1793624647,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-5-0-pro/xxx.jpeg?X-Tos-Algorithm=...&X-Tos-Expires=86400&...",
      "size": "1024x1024",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}

成功响应示例（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`	参数不合法，如 `size` 的总像素超出范围。按错误信息调整后重试
400	`MissingParameter`	缺少 `prompt` 或 `prompt` 为空
401	—	`无效的令牌`。检查 API Key 是否正确、是否已被禁用
429	—	请求频率超限。请降低调用频率，或联系商务提升配额
500	—	服务端内部错误。请稍后重试，若持续出现请提交工单

4.3 错误响应示例

尺寸不合规：

{
  "error": {
    "message": "The parameter `size` specified in the request are not valid: image area must be at least 921600 pixels. Request id: 0217936247303956...",
    "type": "BadRequest",
    "param": "size",
    "code": "InvalidParameter"
  }
}

提示词为空：

{
  "error": {
    "message": "The request failed because it is missing `prompt` parameter. Request id: 0217936245939496...",
    "type": "BadRequest",
    "param": "prompt",
    "code": "MissingParameter"
  }
}

认证失败：

{
  "error": {
    "code": "",
    "message": "无效的令牌 (request id: 20261102131816233158317HmAGSQf7)",
    "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 计费方式

图像生成按张计费，单价以模型广场为准，实际扣费请以控制台日志为准。响应 usage 中的 token 数按 宽 × 高 ÷ 256 计算，仅供参考：

尺寸	像素数	usage.output_tokens
1024x1024	1,048,576	4,096
1920x1920	3,686,400	14,400
2048x2048	4,194,304	16,384
2560x1440	3,686,400	14,400

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 常见注意事项

尺寸选择：优先使用推荐尺寸；自定义尺寸需满足总像素 921,600 ～ 4,624,220。

URL 及时下载：图像 URL 有有效期，生产环境应在收到响应后立即转存到自有存储。

Base64 适用场景：下游系统不便访问外部 URL（如内网环境）时，可使用 b64_json 直接获取图像数据。Base64 会使响应体显著增大。

超时设置：单张图通常需要 10～60 秒，请把客户端超时设为 120 秒以上。

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

8. qwen-image-2.0-pro

qwen-image-2.0-pro 同样通过本接口调用，请求格式不变：

响应（URL 已截断）：

{
  "data": [
    {
      "url": "https://dashscope-0484.oss-accelerate.aliyuncs.com/.../80d775f4-ecd3-4ca3-b2ff-2db65b8db6c0.png?Expires=1794230605&...",
      "b64_json": "",
      "revised_prompt": ""
    }
  ],
  "created": 1793624793,
  "metadata": {
    "output": {"choices": [{"finish_reason": "stop", "message": {"content": [{"image": "https://..."}], "role": "assistant"}}]},
    "usage": {"height": 1024, "image_count": 1, "width": 1024},
    "request_id": "c674c35e-7b50-9a91-9c31-b772776d0715"
  }
}

项目	说明
尺寸	总像素需在 512x512 ～ 2048x2048 之间（262,144 ～ 4,194,304），如 `1024x1024`、`2048x2048`
图像格式	PNG
链接有效期	约 7 天（见链接中的 `Expires` 参数）
结果字段	读取 `data[0].url`；`metadata` 为模型原始返回，可忽略

9. 接口参数与行为说明

参数/行为	`doubao-seedream-5-0-260128`
`size`	宽高自由组合，总像素 921,600 ～ 4,624,220
`n`	请保持 `1`
`quality`、`style`	接受传入，不影响输出
`response_format`	`url` / `b64_json`
返回图像格式	JPEG
`data[].size`	返回实际生成尺寸
`usage`	返回 token 数（仅供参考，按张计费）

10. 技术支持

如在接入或使用过程中遇到问题，请通过控制台右下角的在线客服联系我们，并附上响应头中的 X-Oneapi-Request-Id。

图像生成接口文档

1. 概述#

1.1 核心能力#

2. 鉴权方式#

3. 接口定义#

3.1 基本信息#

3.2 请求参数#

请求示例#

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 计费方式#

6.2 图像 URL 有效期#

7. 最佳实践#

7.1 提示词撰写指南#

7.2 常见注意事项#

8. qwen-image-2.0-pro#

9. 接口参数与行为说明#

10. 技术支持#

1. 概述

1.1 核心能力

2. 鉴权方式

3. 接口定义

3.1 基本信息

3.2 请求参数

请求示例

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 计费方式

6.2 图像 URL 有效期

7. 最佳实践

7.1 提示词撰写指南

7.2 常见注意事项

8. qwen-image-2.0-pro

9. 接口参数与行为说明

10. 技术支持