> ## 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
> Generate images with gpt-image-2, including asynchronous tasks and JSON reference images.
`gpt-image-2` is the DimiLinks image generation model. It supports text-to-image and image-to-image workflows, with up to nine reference images supplied through `image_urls`.
We recommend adding `?async=true`. Synchronous mode waits for image generation to finish before returning and is more likely to be interrupted by a gateway or client timeout.
## Request URL
```http theme={null}
POST https://dimilinks.com/v1/images/generations?async=true
Content-Type: application/json
Authorization: Bearer
```
## Text-to-image example
```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": "A cyberpunk poster of a cat, neon lighting, cinematic atmosphere",
"n": 1,
"size": "16:9",
"resolution": "2k",
"output_format": "png"
}'
```
## Image-to-image example
```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": "Keep the person consistent and restyle the image as a cinematic beach portrait at sunset",
"n": 1,
"size": "16:9",
"resolution": "4k",
"image_urls": [
"https://example.com/reference.png"
]
}'
```
## Asynchronous response
```json theme={null}
{
"created": 1777080000,
"task_id": "img_xxx",
"data": []
}
```
After receiving `task_id`, call [Retrieve image task](/en/api-reference/images/gpt-image-2/tasks) to retrieve the result.
## Synchronous response
Synchronous mode returns after the image is ready:
```json theme={null}
{
"created": 1777080000,
"task_id": "img_xxx",
"data": [
{
"url": "/p/img/img_xxx/0?exp=1777166400000&sig=...",
"file_id": "file_xxx"
}
]
}
```
## Result fields
`data[].url` is not always a public image URL. Support all three forms:
* `/p/img/...`: a relative path. Prefix it with `https://dimilinks.com` before displaying or downloading it. The path requires no Bearer token because the URL includes a signature and expiration time.
* `https://...`: a complete image URL that can be requested or displayed directly.
* `data:image/...;base64,...`: a Data URL containing the image itself. A webpage can use it directly as `![]()
`; a server-side script must decode the base64 before saving it as a file.
## Parameters
| Parameter | Type | Default | Description |
| -------------------- | ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| `model` | string | `gpt-image-2` | Model name. |
| `prompt` | string | Required | Generation or editing prompt. |
| `n` | integer | `1` | Number of images generated per request. The `1k` tier is fixed at `1`; `2k` and `4k` support up to `4`. |
| `size` | string | `1024x1024` | Aspect ratio such as `1:1` or `16:9`, or exact `WxH` pixels such as `3840x2160`. |
| `resolution` | string | Empty | Resolution tier: `1k` / `2k` / `4k`. |
| `output_format` | string | Empty | Output format: `png` / `jpeg` / `webp`. |
| `output_compression` | integer | Empty | Output compression quality for `jpeg` or `webp`. |
| `background` | string | Empty | Background preference: `auto` / `transparent` / `opaque`. |
| `moderation` | string | Empty | Content moderation level: `auto` / `low`. |
| `user` | string | Empty | Caller-side user identifier for auditing. |
| `wait_for_result` | boolean | `true` | Set to `false` for asynchronous submission. |
| `image_urls` | string \| array \| object | Empty | JSON reference-image field, with up to nine images. |
| `mask_url` | string | Empty | Inpainting mask; requires at least one reference image. |
| `response_format` | string | Empty | Set to `b64_json` to return base64 directly; not recommended as the default. |
## Enable asynchronous mode
Any one of the following enables asynchronous mode:
* Query parameter: `?async=true`
* Query parameter: `?wait_for_result=false`
* Request header: `Prefer: respond-async`
* Request body: `"wait_for_result": false`
## Reference-image format
We recommend `image_urls`:
```json theme={null}
{
"image_urls": [
"https://example.com/ref.png",
"data:image/png;base64,iVBORw0KGgo..."
]
}
```
The API also accepts `reference_images`, `images`, `image`, `image_url`, `input_image`, and `input_images`.
## Reference-image limits
* A request can include up to nine reference images.
* Each reference image can be up to 20 MB.
* HTTP(S) URLs, Data URLs, and raw base64 are supported.
* Browser `blob:` URLs cannot be submitted directly. Upload the image to your server or convert it to a Data URL first.
## Differences between resolution tiers
| Tier | Maximum `n` per request | Typical time | Description |
| ---- | ----------------------: | ----------------: | -------------------------------------------------------------------------------- |
| `1k` | 1 | About 60 seconds | Entry tier for previews or low-cost batch generation. |
| `2k` | 4 | About 120 seconds | Recommended tier for most production image generation. |
| `4k` | 4 | About 180 seconds | High-fidelity tier that also supports some extreme aspect ratios such as `21:9`. |
See the Pricing page in the console for current prices. Each resolution tier is priced independently.
## 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
````