# Seedream 5.0 Pro

> 通过 UniAI.ai 同步图片接口调用 seedream-5.0-pro 生成或编辑图片。

Canonical URL: https://docs.uniai.tv/models/image/seedream-5-0-pro
Locale: zh-CN

使用 `seedream-5.0-pro` 时，文生图和图片编辑分别调用对应的同步接口。文生图使用 `/v1/images/generations` 且不传 `image`；图生图或图片编辑使用 `/v1/images/edits`，并传入 1 至 10 张参考图。

本文档对应 2026 年 7 月 25 日更新的公开调用契约。

## 概览

- 两个接口都在同一个 HTTP 响应中返回最终图片，不需要创建或轮询异步任务。
- 每次请求固定生成一张图片。
- 可以使用 `1K` 或 `2K` 分辨率档位并指定画幅比例，也可以直接传入精确尺寸。
- 参考图支持公网 URL 和 Base64 Data URL。
- 响应可以返回临时图片 URL 或纯 Base64 数据。

## 接口与鉴权

```http
POST https://api.uniai.tv/v1/images/generations
POST https://api.uniai.tv/v1/images/edits
Authorization: Bearer sk-***
Content-Type: application/json
```

- 文生图：调用 `/v1/images/generations`，不传 `image`。
- 图生图或图片编辑：调用 `/v1/images/edits`，并传入 `image`。

Base URL 为：

```uri
https://api.uniai.tv
```

如果 UniAI.ai 控制台为当前账号提供了专属 API 地址，请以控制台显示的地址为准。

## 快速开始

### 文生图

```bash
curl -X POST "https://api.uniai.tv/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "高端护肤品广告图，玻璃瓶放在浅色石材台面上，柔和自然光，中文品牌文字清晰",
    "size": "2K",
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

### 图生图

```bash
curl -X POST "https://api.uniai.tv/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "保留产品外形和标签文字，把背景替换成明亮的摄影棚场景",
    "image": "https://example.com/source-product.png",
    "size": "1K",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "response_format": "url"
  }'
```

### 精确尺寸

需要固定宽高时，直接把精确尺寸传给 `size`。同一个请求中不要再传 `aspect_ratio`。

```bash
curl -X POST "https://api.uniai.tv/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "宽幅科技产品发布会主视觉，主体位于画面中央，背景简洁",
    "size": "2048x1024",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | 无 | 固定为 `seedream-5.0-pro`。 |
| `prompt` | string | 是 | 无 | 图片生成或编辑提示词。 |
| `image` | string / string[] | 图生图必填 | 无 | `/v1/images/edits` 的参考图，支持公网 URL 或 Base64 Data URL，最多 10 张。 |
| `size` | string | 否 | `2K` | `1K`、`2K` 或精确尺寸 `WIDTHxHEIGHT`。 |
| `aspect_ratio` | string | 否 | 由模型判断 | 使用 `1K`、`2K` 时可指定画幅比例；精确尺寸模式不能传。 |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png`。 |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json`。 |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印。 |

该模型每次固定生成一张图片。

## 尺寸与画幅比例

尺寸有以下两种用法，选择其中一种。

### 分辨率档位与画幅比例

```json
{
  "size": "2K",
  "aspect_ratio": "16:9"
}
```

`size` 支持 `1K` 和 `2K`。`aspect_ratio` 支持 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3` 和 `21:9`。

常见输出尺寸如下。最终尺寸以响应中的 `data[0].size` 为准。

| 分辨率 | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` |
| `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` |

不传 `aspect_ratio` 时，模型会根据提示词和参考图判断画幅。

### 精确尺寸

```json
{
  "size": "2048x1024"
}
```

精确尺寸必须同时满足以下条件：

- `width * height` 必须在 `921600` 到 `4624220` 之间，包含边界值。
- 宽高比必须在 `1/16` 到 `16` 之间，包含边界值。
- 没有单独的 4096 最大边限制，例如 `4200x1000` 是合法尺寸。
- 不能同时传 `aspect_ratio`，因为精确尺寸已经确定画幅。

## 参考图输入

图生图和图片编辑统一调用 `/v1/images/edits`。

单张参考图传字符串，多张参考图传数组：

```json
{
  "image": [
    "https://example.com/product.png",
    "data:image/png;base64,..."
  ]
}
```

同一个请求中可以混合使用公网 URL 和 Base64 Data URL。

### 公网 URL

- 图片必须能被公网直接访问。
- 访问图片不能依赖 Cookie、登录状态或额外请求头。

### Base64 Data URL

必须使用完整的 Data URL 格式：

```uri
data:image/png;base64,...
```

- 图片格式名必须小写，但不要求 Base64 内容本身小写。
- 支持 JPEG、PNG、WEBP、BMP、TIFF、GIF、HEIC 和 HEIF。
- 每张 Data URL 图片最大 `30 MB`。
- 单次请求的参考图总数不能超过 10 张。

## 响应格式

输入形式和输出形式相互独立。URL 输入可以返回 Base64，Base64 输入也可以返回 URL。

### URL 响应

请求参数：

```json
{
  "response_format": "url"
}
```

响应示例：

```json
{
  "created": 1784900000,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "2816x1584",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 17424,
    "total_tokens": 17424
  }
}
```

返回的 URL 可能在生成后 24 小时失效，请及时下载并保存图片。

### Base64 响应

请求参数：

```json
{
  "response_format": "b64_json"
}
```

图片项会返回 `b64_json`，不再返回 `url`：

```json
{
  "data": [
    {
      "b64_json": "...",
      "size": "2048x1024",
      "output_format": "png"
    }
  ]
}
```

`b64_json` 是纯 Base64 内容，不包含 Data URL 前缀。

### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `created` | integer | 响应的 Unix 时间戳。 |
| `data` | array | 生成结果数组，固定包含一个图片项。 |
| `data[].url` | string | `response_format` 为 `url` 时返回的临时图片地址。 |
| `data[].b64_json` | string | `response_format` 为 `b64_json` 时返回的纯 Base64 图片数据。 |
| `data[].size` | string | 最终输出尺寸，格式为 `WIDTHxHEIGHT`。 |
| `data[].output_format` | string | 最终图片格式。 |
| `usage.generated_images` | integer | 生成图片数量。 |
| `usage.input_images` | integer | 输入参考图数量。 |
| `usage.output_tokens` | integer | API 返回的输出用量。 |
| `usage.total_tokens` | integer | API 返回的总用量。 |

## 提示词定位与标注

点位、区域、文字替换、箭头、涂鸦和标注框都通过输入图与 `prompt` 表达，不需要增加请求参数。

```markdown
把 <bbox>100 200 800 900</bbox> 内的招牌替换为“新品上市”
在 <point>520 380</point> 附近增加一个小型台灯
```

坐标范围为 `0..999`。也可以直接在输入图中绘制箭头、标注框或其他标记，再通过提示词说明编辑意图。

## 计费说明

- 每次请求固定输出一张图片。
- 输入图片张数可能参与计费，具体以当前 UniAI.ai 模型页为准。
- 输出图片按实际像素分档：不超过 `2360000` 像素，或超过 `2360000` 像素。
- `1K`、`2K` 不是直接计费条件，最终根据生成图片的 `width * height` 判断档位。
- 具体单价、分组倍率和最终扣费以 UniAI.ai 模型页及消费日志为准。

## 常见问题

| 问题 | 常见原因 | 处理方式 |
| --- | --- | --- |
| 传入参考图后没有按编辑请求处理 | 请求发送到了 `/v1/images/generations`。 | 所有包含 `image` 的请求都改用 `/v1/images/edits`。 |
| 精确尺寸被拒绝 | 同时传了 `aspect_ratio`，或像素数、宽高比超出限制。 | 删除 `aspect_ratio`，并重新检查精确尺寸约束。 |
| 参考图被拒绝 | 超过 10 张、URL 无法公网直连，或 Data URL 格式不完整。 | 减少图片数量，并检查公网访问或完整 Data URL 格式。 |
| 图片格式被拒绝 | 使用了不支持的格式，或 Data URL 中的图片格式名不是小写。 | 改用支持的格式，并使用 `image/png` 等小写格式名。 |
| 响应中找不到预期字段 | 请求 `b64_json` 后仍读取 `url`，或反之。 | 根据 `response_format` 读取对应字段。 |
| 客户端在返回图片前超时 | 同步生成所需时间超过客户端 HTTP 超时。 | 增加客户端超时时间，继续等待原请求，不要轮询异步任务接口。 |

## 相关页面

- [图像生成概览](/models/image/overview)
- [模型列表](/models)