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

# Create image generation

> 用 gpt-image-2 生成图片，支持异步任务和 JSON 参考图。

`gpt-image-2` 是 DimiLinks 的图片生成模型，支持文生图与图生图。可以通过 `image_urls` 字段携带参考图，最多 9 张。

<Note>
  推荐加上 `?async=true`。同步模式会等图片完成后才返回，更容易被网关或客户端超时打断。
</Note>

## 请求地址

```http theme={null}
POST https://dimilinks.com/v1/images/generations?async=true
Content-Type: application/json
Authorization: Bearer <DIMILINKS_API_KEY>
```

## 文生图示例

```bash theme={null}
curl "https://dimilinks.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $DIMILINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张赛博朋克风格的猫咪海报，霓虹灯，电影感",
    "n": 1,
    "size": "16:9",
    "resolution": "2k",
    "output_format": "png"
  }'
```

## 图生图示例

```bash theme={null}
curl "https://dimilinks.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $DIMILINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保持人物主体一致，改成海边日落电影写真风格",
    "n": 1,
    "size": "16:9",
    "resolution": "4k",
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'
```

## 异步响应

```json theme={null}
{
  "created": 1777080000,
  "task_id": "img_xxx",
  "data": []
}
```

拿到 `task_id` 后，请调用 [Retrieve image task](/api-reference/images/gpt-image-2/tasks) 查询结果。

## 同步响应

同步模式会在图片完成后返回：

```json theme={null}
{
  "created": 1777080000,
  "task_id": "img_xxx",
  "data": [
    {
      "url": "/p/img/img_xxx/0?exp=1777166400000&sig=...",
      "file_id": "file_xxx"
    }
  ]
}
```

## 结果字段说明

`data[].url` 不一定是公网图片链接，请同时兼容三种形式：

* `/p/img/...`：相对路径，展示或下载前补成 `https://dimilinks.com/p/img/...`。该路径不需要 Bearer，URL 自带签名和过期时间。
* `https://...`：完整图片链接，可直接请求或展示。
* `data:image/...;base64,...`：Data URL，字符串本身就是图片内容。网页可直接作为 `<img src>`；服务端脚本保存文件时需要先解码 base64。

## 参数

| 参数                   | 类型                        | 默认值           | 说明                                            |
| -------------------- | ------------------------- | ------------- | --------------------------------------------- |
| `model`              | string                    | `gpt-image-2` | 模型名称。                                         |
| `prompt`             | string                    | 必填            | 生图或编辑提示词。                                     |
| `n`                  | integer                   | `1`           | 单次生成数量。`1k` 档固定为 `1`，`2k` / `4k` 档最多 `4`。     |
| `size`               | string                    | `1024x1024`   | 比例如 `1:1`、`16:9`，或具体像素 `WxH`（例如 `3840x2160`）。 |
| `resolution`         | string                    | 空             | 清晰度档位：`1k` / `2k` / `4k`。                     |
| `output_format`      | string                    | 空             | 输出格式：`png` / `jpeg` / `webp`。                 |
| `output_compression` | integer                   | 空             | 输出压缩质量，配合 `jpeg` 或 `webp` 使用。                 |
| `background`         | string                    | 空             | 背景偏好：`auto` / `transparent` / `opaque`。       |
| `moderation`         | string                    | 空             | 内容审核强度：`auto` / `low`。                        |
| `user`               | string                    | 空             | 调用方用户标识，便于审计。                                 |
| `wait_for_result`    | boolean                   | `true`        | 传 `false` 进入异步提交。                             |
| `image_urls`         | string \| array \| object | 空             | JSON 参考图字段，最多 9 张。                            |
| `mask_url`           | string                    | 空             | 局部重绘遮罩，需配合至少 1 张参考图。                          |
| `response_format`    | string                    | 空             | 传 `b64_json` 时返回结果直接是 base64；不建议默认开启。         |

## 开启异步的方式

任一方式命中即可进入异步模式：

* 查询参数：`?async=true`
* 查询参数：`?wait_for_result=false`
* 请求头：`Prefer: respond-async`
* 请求体：`"wait_for_result": false`

## 参考图格式

推荐使用 `image_urls`：

```json theme={null}
{
  "image_urls": [
    "https://example.com/ref.png",
    "data:image/png;base64,iVBORw0KGgo..."
  ]
}
```

也兼容 `reference_images`、`images`、`image`、`image_url`、`input_image` 和 `input_images`。

## 参考图限制

* 同一次请求最多 9 张参考图。
* 单张参考图最大 20 MB。
* 支持 HTTP(S) URL、Data URL 和纯 base64。
* 浏览器 `blob:` URL 不能直接传入，请先上传到你的服务端或转成 Data URL。

## 清晰度档位的能力差异

| 档位   | 单次最多 `n` |    典型耗时 | 说明                        |
| ---- | -------: | ------: | ------------------------- |
| `1k` |        1 |  约 60 秒 | 起步档，适合预览或低成本批量。           |
| `2k` |        4 | 约 120 秒 | 推荐档，适合大多数业务出图。            |
| `4k` |        4 | 约 180 秒 | 高保真档，部分极端比例（如 `21:9`）也可用。 |

具体单价以控制台「价格」页为准；不同档位的价格独立计算。


## OpenAPI

````yaml POST /images/generations
openapi: 3.1.0
info:
  title: DimiLinks API
  description: >-
    DimiLinks unified API for chat (OpenAI-compatible and Anthropic native),
    image generation/editing, and video generation.
  version: 1.1.0
servers:
  - url: https://dimilinks.com/v1
    description: OpenAI 兼容入口：chat completions / images / videos / models / tasks
security:
  - bearerAuth: []
tags:
  - name: Models
  - name: Chat
  - name: Images
  - name: Videos
  - name: Tasks
paths:
  /images/generations:
    post:
      tags:
        - Images
      summary: Create image generation
      operationId: createImageGeneration
      parameters:
        - name: async
          in: query
          description: Set to true to submit an async image task.
          schema:
            type: boolean
        - name: wait_for_result
          in: query
          description: Set to false to submit an async image task.
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
      responses:
        '200':
          description: Image generation result or async submission
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ImageSubmitResponse'
                  - $ref: '#/components/schemas/ImageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ImageGenerationRequest:
      type: object
      properties:
        model:
          type: string
          default: gpt-image-2
        prompt:
          type: string
        'n':
          type: integer
          default: 1
          minimum: 1
          maximum: 4
          description: 1k resolution allows n=1 only; 2k and 4k allow up to 4.
        size:
          type: string
          examples:
            - '1:1'
            - '16:9'
            - 3840x2160
        resolution:
          type: string
          enum:
            - 1k
            - 2k
            - 4k
        output_format:
          type: string
          examples:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
        background:
          type: string
          examples:
            - auto
            - transparent
            - opaque
        moderation:
          type: string
          examples:
            - auto
            - low
        wait_for_result:
          type: boolean
        image_urls:
          $ref: '#/components/schemas/ReferenceImages'
        mask_url:
          type: string
        response_format:
          type: string
          examples:
            - b64_json
        user:
          type: string
      required:
        - prompt
    ImageSubmitResponse:
      type: object
      properties:
        created:
          type: integer
          example: 1777080000
        task_id:
          type: string
          example: img_xxx
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageData'
          example: []
      required:
        - task_id
        - data
    ImageResponse:
      type: object
      properties:
        created:
          type: integer
          example: 1777080000
        task_id:
          type: string
          example: img_xxx
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageData'
    ReferenceImages:
      oneOf:
        - type: string
        - type: array
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: true
          maxItems: 9
        - type: object
          additionalProperties: true
    ImageData:
      type: object
      properties:
        url:
          type: string
          example: /p/img/img_xxx/0?exp=1777166400000&sig=...
        file_id:
          type: string
          example: file_xxx
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
          example: invalid_request_error
        code:
          oneOf:
            - type: string
            - type: integer
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Model is not allowed for this API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````