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

# OpenAI 兼容的图像生成

> 通过标准的 POST /v1/images/generations endpoint，使用 Seedream、Wan、gpt-image-2 和 GPT Image 2.5 生成图像。请求结构为 OpenAI 兼容；Seedream 路由要求图像最小尺寸为 3,686,400 像素（例如 1920×1920）。

标准的 OpenAI 兼容 `POST /v1/images/generations` endpoint。截至 2026 年 9 月 30 日，它服务 `seedream-5-0-260128`、`wan2.7-image`、`wan2.7-image-pro`、`gpt-image-2`、`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst`。较早的 `seedream-4-5-251128` 路由改为通过[经由 Chat 的图像生成](/docs/zh/api-reference/chat/post_chat-completions-image-generation)访问。

## 路由速览

| 模型 | Endpoint |
| - | - |
| `seedream-5-0-260128` | **`POST /v1/images/generations`** *(本页)*，同时支持 `POST /v1/chat/completions` |
| `wan2.7-image` / `wan2.7-image-pro` | **`POST /v1/images/generations`** *(本页)*、`POST /v1/images/edits` |
| `gpt-image-2` | **`POST /v1/images/generations`** *(本页)*、`POST /v1/images/edits` |
| `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` | **`POST /v1/images/generations`** *(本页)*、`POST /v1/images/edits` |
| `seedream-4-5-251128` | [`POST /v1/chat/completions`](/docs/zh/api-reference/chat/post_chat-completions-image-generation) |
| Gemini 兼容模型 | [`POST /v1beta/models/{model}:generateContent`](/docs/zh/api-reference/chat/post_models-model-generatecontent) |

## 支持的模型

| 模型 | 计费方式 | 说明 |
| - | - | - |
| `seedream-5-0-260128` | 按次请求 | 图像最小尺寸 **3,686,400 像素**（例如 1920×1920） |
| `wan2.7-image` | 按次请求 | 同时支持 `POST /v1/images/edits` |
| `wan2.7-image-pro` | 按次请求 | 质量更高的 Wan 路由 |
| `gpt-image-2` | 按次请求或按张图片；部分路由同时适用 token 计价 | 参见 [AI 模型价格](/docs/zh/guides/pricing/ai-model-pricing-llm-inference) |
| `gpt-image-2.5-flare` | 按 1M Token：输入、输出、缓存读取 | GPT Image 2.5 路由 |
| `gpt-image-2.5-sunburst` | 按 1M Token：输入、输出、缓存读取 | GPT Image 2.5 路由 |

当前价格见 [aisa.one/models](https://aisa.one/models)。

## 尺寸限制 ⚠️（Seedream 路由）

Seedream 上游强制要求最少 **3,686,400 像素**。低于该值的请求会被拒绝：

```
400 InvalidParameter: image size must be at least 3686400 pixels
```

| 尺寸 | 像素数 | 是否接受？ |
| - | - | - |
| `1024x1024` | 1,048,576 | ❌ |
| `1536x1536` | 2,359,296 | ❌ |
| `1920x1920` | 3,686,400 | ✅（正好达到阈值） |
| `2048x2048` | 4,194,304 | ✅ |
| `2304x1600` | 3,686,400 | ✅ |
| `2560x1920` | 4,915,200 | ✅ |

只要 `宽 × 高 ≥ 3,686,400`，任意宽高比都可以。

## 请求

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.aisa.one/v1/images/generations" \
    -H "Authorization: Bearer $AISA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedream-5-0-260128",
      "prompt": "A cute red panda, ultra-detailed, cinematic lighting",
      "n": 1,
      "size": "2048x2048"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(base_url="https://api.aisa.one/v1", api_key="sk-aisa-...")

  resp = client.images.generate(
      model="seedream-5-0-260128",
      prompt="A cute red panda, ultra-detailed, cinematic lighting",
      n=1,
      size="2048x2048",
  )

  for item in resp.data:
      print(item.url)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.aisa.one/v1",
    apiKey: process.env.AISA_API_KEY,
  });

  const resp = await client.images.generate({
    model: "seedream-5-0-260128",
    prompt: "A cute red panda, ultra-detailed, cinematic lighting",
    n: 1,
    size: "2048x2048",
  });

  for (const item of resp.data) {
    console.log(item.url);
  }
  ```
</CodeGroup>

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `seedream-5-0-260128`、`wan2.7-image`、`wan2.7-image-pro`、`gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 之一 |
| `prompt` | string | 是 | 要生成图像的文字描述 |
| `n` | integer | 否 | 生成图像数量。每张按该模型的单次请求费率单独计费 |
| `size` | string | 否 | `宽x高`。Seedream 路由必须满足 `宽 × 高 ≥ 3,686,400`；`wan2.7-image` 和 `gpt-image-2` 可接受更小尺寸（已验证 `1024x1024` 可用） |

## 响应

```json theme={null}
{
  "model": "seedream-5-0-260128",
  "created": 1776495432,
  "data": [
    {
      "url": "https://cdn.aisa.one/images/seedream/...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

**AIsa 的响应在原生 OpenAI schema 之上增加了几处扩展：**

* 根层级回显 `model`
* `data[].size`——每张返回图像的实际尺寸
* `usage`——包含 `generated_images`（用于计费），以及用于 token 核算的 `output_tokens` / `total_tokens`

<Warning>
  `data[].url` 中的 URL **有效期很短**。请在过期前下载并保存到你自己的存储中。
</Warning>

## 常见 4xx 原因

* `400 InvalidParameter — image size must be at least 3686400 pixels`——`size` 太小。请使用 `1920x1920` 或更大。
* `404 openai_error`——传入的模型不走该 endpoint（例如 `wan2.7-image`）。请改用[基于 chat 的路由](/docs/zh/api-reference/chat/post_chat-completions-image-generation)。
* `400 invalid_request`——`size` 字符串格式不正确（例如写成 `1024` 而不是 `1024x1024`）。

更多内容参见[错误码](/docs/zh/api-reference/errors)和[速率限制](/docs/zh/api-reference/rate-limits)。

## 相关

<CardGroup cols={3}>
  <Card title="Image Generation via Chat" icon="message" href="/docs/zh/api-reference/chat/post_chat-completions-image-generation">
    Wan 2.7 系列使用的 `/v1/chat/completions` 路由。
  </Card>

  <Card title="Gemini generateContent" icon="google" href="/docs/zh/api-reference/chat/post_models-model-generatecontent">
    Gemini 兼容的 generateContent endpoint。
  </Card>

  <Card title="Media Gen skill" icon="image" href="/docs/agent-skills/mediagen">
    封装图像与视频生成的 Agent 技能。
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi/zh/openai-images-generations.json POST /images/generations
openapi: 3.0.3
info:
  title: OpenAI-Compatible Image Generations
  version: 1.0.0
  description: >-
    标准的 OpenAI 兼容 `POST /v1/images/generations` endpoint。截至 2026 年 9 月 30 日，它服务
    `seedream-5-0-260128`、`wan2.7-image`、`wan2.7-image-pro`、`gpt-image-2`、`gpt-image-2.5-flare`
    和 `gpt-image-2.5-sunburst`。较早的 `seedream-4-5-251128` 改为通过
    [`/v1/chat/completions`](/api-reference/chat/post_chat-completions-image-generation)
    路由，而 Gemini 兼容的 `generateContent` 请求使用
    [`/v1beta/models/{model}:generateContent`](/api-reference/chat/post_models-model-generatecontent)。
servers:
  - url: https://api.aisa.one/v1
security:
  - BearerAuth: []
paths:
  /images/generations:
    post:
      summary: 生成图像（OpenAI 兼容）
      description: >-
        使用 OpenAI 兼容的 images-generations endpoint 生成图像。


        **尺寸限制（仅 Seedream 路由）。** Seedream 上游要求每张图像至少 **3,686,400 像素**。低于该值的请求会返回
        `400 InvalidParameter: image size must be at least 3686400 pixels`。Wan 和
        `gpt-image-2` 路由可接受更小尺寸——`wan2.7-image` 已验证 `1024x1024` 可用。
      operationId: createImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  enum:
                    - seedream-5-0-260128
                    - wan2.7-image
                    - wan2.7-image-pro
                    - gpt-image-2
                    - gpt-image-2.5-flare
                    - gpt-image-2.5-sunburst
                  description: >-
                    图像生成模型。`seedream-5-0-260128`、`wan2.7-image`、`wan2.7-image-pro`、`gpt-image-2`、`gpt-image-2.5-flare`
                    或 `gpt-image-2.5-sunburst`。
                prompt:
                  type: string
                  description: 要生成的图像的文本描述。
                'n':
                  type: integer
                  minimum: 1
                  default: 1
                  description: 要生成的图像数量。每张图像均按单张图像费率单独计费。
                size:
                  type: string
                  description: >-
                    图像尺寸，格式为 `宽x高`。Seedream 路由要求 `宽 × 高 ≥ 3,686,400`（例如
                    `1920x1920`、`2048x2048`）；Wan 和 `gpt-image-2` 可接受更小尺寸，如
                    `1024x1024`。
                  example: 2048x2048
            examples:
              basic:
                summary: Single 2K image
                value:
                  model: seedream-5-0-260128
                  prompt: A cute red panda, ultra-detailed, cinematic lighting
                  'n': 1
                  size: 2048x2048
              minimum_size:
                summary: Exactly at minimum allowed size (1920×1920)
                value:
                  model: seedream-5-0-260128
                  prompt: A futuristic cyberpunk city, neon lights, rainy night, 8k
                  'n': 1
                  size: 1920x1920
              batch:
                summary: Four candidates for selection
                value:
                  model: seedream-5-0-260128
                  prompt: Oil painting of a rolling hillside at sunset
                  'n': 4
                  size: 2048x2048
      responses:
        '200':
          description: 图像生成成功。
          content:
            application/json:
              schema:
                type: object
                properties:
                  model:
                    type: string
                    example: seedream-5-0-260128
                  created:
                    type: integer
                    example: 1776495432
                  data:
                    type: array
                    description: 每张生成的图像对应一个条目。
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: 生成图像的短期有效 URL。请下载并持久化保存；该 URL 会过期。
                        size:
                          type: string
                          description: 返回图像的实际尺寸。
                  usage:
                    type: object
                    properties:
                      generated_images:
                        type: integer
                      output_tokens:
                        type: integer
                      total_tokens:
                        type: integer
              example:
                model: seedream-5-0-260128
                created: 1776495432
                data:
                  - url: https://cdn.aisa.one/images/seedream/20260418-abc.png
                    size: 2048x2048
                usage:
                  generated_images: 1
                  output_tokens: 16384
                  total_tokens: 16384
        '400':
          description: >-
            请求无效。最常见的情况：`size` 小于 3,686,400 像素 → `"image size must be at least
            3686400 pixels"`。
        '401':
          description: AIsa API 密钥缺失或无效。
        '404':
          description: >-
            该模型不走此 endpoint。网关会返回
            `model_route_not_supported`，并附上该模型实际支持的路由——参见[模型目录](/guides/models)。
        '429':
          description: 已达到速率限制。
        '500':
          description: 内部错误。
        '502':
          description: 无法连接上游提供商。
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AISA API Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.