> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream 5.0 Pro

> Dola Seedream 5.0 Pro 文生图、图生图与多图参考

## 简介

Seedream 5.0 Pro（模型 `dola-seedream-5-0-pro-260628`）支持文生图、单图生图/图片编辑、多图参考/图片融合。通过 OpenAI 兼容的图片生成接口同步调用，当前单次请求实际输出 **1 张**图片。

多张参考图表示**输入**多张图片，不表示输出多张。需要多张结果时，请分别发起多次请求。

完整多模型对比也可参见 [图片生成](/cn/api-reference/endpoint/image-generation)。

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxx`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

API Key 在平台的 API 密钥页面创建。请勿将 API Key 写入前端代码、公开仓库或客户端安装包。

## 模型信息

| 项目          | 说明                             |
| ----------- | ------------------------------ |
| 模型名称        | `dola-seedream-5-0-pro-260628` |
| 文生图         | 支持                             |
| 单图生图 / 图片编辑 | 支持                             |
| 多图参考 / 图片融合 | 支持                             |
| 单次输出数量      | 当前为 1 张                        |
| 接口协议        | OpenAI 兼容图片生成接口                |
| 接口类型        | 同步返回                           |

## 接口地址

```http theme={null}
POST https://api.gravitex.ai/v1/images/generations
```

## 请求参数

| 参数                | 类型        | 必填 | 说明                                       |
| ----------------- | --------- | -- | ---------------------------------------- |
| `model`           | string    | 是  | 固定为 `dola-seedream-5-0-pro-260628`       |
| `prompt`          | string    | 是  | 图片生成或编辑指令                                |
| `size`            | string    | 否  | 输出尺寸，可使用 `1K`、`2K` 或 `宽x高`，如 `1024x1024` |
| `images`          | string\[] | 否  | 参考图片 URL 数组；不传时为文生图                      |
| `n`               | integer   | 否  | 请求生成数量；该模型当前实际只返回 1 张，建议使用 `1`           |
| `quality`         | string    | 否  | 图片质量，使用 `standard`                       |
| `output_format`   | string    | 否  | 输出格式，支持 `jpeg`、`png`，默认 `jpeg`           |
| `response_format` | string    | 否  | 返回方式，支持 `url` 或 `b64_json`，默认 `url`      |
| `watermark`       | boolean   | 否  | 是否添加水印；`true` 添加，`false` 不添加，默认 `false`  |

### prompt

必填的文本指令，用于描述希望生成的内容。图生图时，`prompt` 同时用于说明如何使用和修改参考图。

```json theme={null}
"prompt": "未来城市夜景，电影海报风格，高细节，蓝紫色霓虹灯"
```

### images

传入一张或多张可被平台访问的图片 URL：

```json theme={null}
"images": [
  "https://example.com/reference-1.png"
]
```

多图参考示例：

```json theme={null}
"images": [
  "https://example.com/subject.png",
  "https://example.com/style.jpeg"
]
```

<Note>
  * 图片 URL 必须能够被服务端访问，不能只在本地浏览器有效。
  * 多张图片用于参考、融合或编辑，仍生成 1 张结果图。
  * 平台当前测试和生产调用使用 `images` 数组字段。
  * 图片格式、大小、数量和可访问性需同时满足上游模型要求。
</Note>

### size

支持分辨率档位或自定义像素尺寸：

```json theme={null}
"size": "1K"
```

```json theme={null}
"size": "2K"
```

```json theme={null}
"size": "1024x1024"
```

常用尺寸示例：

| 请求尺寸        | 常见实际输出      |
| ----------- | ----------- |
| `1024x1024` | `1024x1024` |
| `2048x2048` | `2048x2048` |

## 调用示例

<Tabs>
  <Tab title="文生图">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "未来城市夜景，电影海报风格",
        "size": "1024x1024",
        "n": 1
      }'
    ```
  </Tab>

  <Tab title="单图生图">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "根据参考图生成一只黑色小羊",
        "size": "1024x1024",
        "n": 1,
        "images": [
          "https://example.com/reference.png"
        ]
      }'
    ```
  </Tab>

  <Tab title="多图融合">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "融合两张参考图，生成一只黑白相间的小羊",
        "size": "1024x1024",
        "n": 1,
        "images": [
          "https://example.com/reference-1.png",
          "https://example.com/reference-2.jpeg"
        ]
      }'
    ```
  </Tab>

  <Tab title="PNG 输出">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "生成一张极简风格的产品宣传图",
        "size": "2K",
        "output_format": "png",
        "watermark": false
      }'
    ```
  </Tab>
</Tabs>

## 成功返回

平台返回 OpenAI 兼容的图片生成结果。典型响应如下：

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "created": 1784868948,
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "1024x1024",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
```

### 返回字段

| 字段                       | 类型      | 说明                                |
| ------------------------ | ------- | --------------------------------- |
| `model`                  | string  | 实际使用的模型名称                         |
| `created`                | integer | 创建时间，Unix 时间戳                     |
| `data`                   | array   | 输出图片列表，当前通常为 1 项                  |
| `data[].url`             | string  | 图片地址；收到后应及时下载并保存                  |
| `data[].b64_json`        | string  | Base64 图片内容，取决于 `response_format` |
| `data[].size`            | string  | 实际输出像素尺寸                          |
| `data[].output_format`   | string  | 实际输出格式                            |
| `usage.input_images`     | integer | 输入参考图数量                           |
| `usage.generated_images` | integer | 成功生成的图片数量                         |
| `usage.output_tokens`    | integer | 图片输出用量 Token                      |
| `usage.total_tokens`     | integer | 请求总用量 Token                       |

<Warning>
  `data[].url` 通常为临时地址。业务系统应在收到响应后立即下载并转存到自己的对象存储。
</Warning>

## 多张图片说明

该模型当前单次请求只返回 1 张图片。下面的请求可以传入 2 张参考图，但结果仍是 1 张：

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "融合两张参考图生成一张新的图片",
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ],
  "n": 1
}
```

如果需要 3 张独立结果，请发起 3 次请求，而不是依赖 `n: 3`：

```text theme={null}
第 1 次请求：n=1
第 2 次请求：n=1
第 3 次请求：n=1
```

## 错误处理

请求失败时通常返回 JSON 错误对象：

```json theme={null}
{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}
```

常见问题：

| 问题          | 处理建议                                |
| ----------- | ----------------------------------- |
| API Key 无效  | 检查 `Authorization: Bearer ...` 是否正确 |
| `prompt` 缺失 | 必须传入非空 `prompt`                     |
| 参考图无法读取     | 检查 URL 是否公网可访问、是否过期                 |
| 尺寸不支持       | 使用 `1K`、`2K` 或符合模型限制的自定义尺寸          |
| 传入不支持参数     | 删除模型不支持的参数后重试                       |
| 希望一次生成多张    | 对该 Pro 模型分别发起多次 `n=1` 请求            |
| 返回 URL 失效   | 收到响应后立即下载并持久化                       |