# Qwen Image

> Qwen Image 3.0, 2.1 and 2.0 generation and editing with OpenAI Images and the Bailian native synchronous API.

Canonical URL: https://docs.uniall.ai/models/image/qwen-image
Locale: en

Generate or edit images with OpenAI Images or the Bailian native API. Both return image URLs synchronously; no task polling is required.

## Models

| Model ID | Maximum reference images |
| --- | --- |
| `qwen-image-3.0-pro` | 3 |
| `qwen-image-3.0` | 3 |
| `qwen-image-2.1-pro` | 10 |
| `qwen-image-2.1-turbo` | 10 |
| `qwen-image-2.0-pro` | 3 |
| `qwen-image-2.0` | 3 |

## Endpoints

Use `https://api.uniall.ai` with `Authorization: Bearer $UNIAI_API_KEY`. Replace the key and reference URLs in the examples with your own values.

| Format | Method | Path |
| --- | --- | --- |
| OpenAI generation | POST | `/v1/images/generations` |
| OpenAI editing (JSON or multipart) | POST | `/v1/images/edits` |
| Bailian native generation and editing | POST | `/api/v1/services/aigc/multimodal-generation/generation` |

## Parameters

For OpenAI JSON, put these fields at the top level. For the native API, keep `model` at the top level, put the prompt and images in `input.messages`, and generation options in `parameters`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | One of the six IDs above. |
| `prompt` | string | Yes | Generation or editing instruction. Native: one `text` item in `input.messages[0].content`. |
| `image` | string or array | Conditional | Ordered reference URLs or image data URLs. Native: one `image` content item per reference. |
| `n` | integer | No | Output count, 1–6; default `1`. |
| `size` | string | No | `WIDTHxHEIGHT`, `WIDTH*HEIGHT`, or `auto`. See limits below. |
| `seed` | integer | No | 0–2147483647. |
| `negative_prompt` | string | No | 3.0 and 2.0 families only. |
| `prompt_extend` | boolean | No | Enable prompt expansion. |
| `prompt_extend_mode` | string | No | `direct` or `agent`; 3.0 and 2.1 only. `agent` is text-to-image only. |
| `enable_thinking` | boolean | No | 3.0 and 2.1 families only. |
| `watermark` | boolean | No | Add a watermark. |
| `response_format` | string | No | OpenAI only: `url`. |

OpenAI also accepts `num_images` as an alias for `n`, and `image_url`, `image_urls`, or `images` for references. Use one reference field; `n` and `num_images` must match if both are present. Generation options may be supplied in `extra_body`; duplicated top-level values must match.

## OpenAI Images {/* #openai-images */}

### Generate

```bash
curl "https://api.uniall.ai/v1/images/generations" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0",
    "prompt": "A blue ceramic cup on a wooden table",
    "n": 1,
    "size": "1024x1024",
    "seed": 0,
    "prompt_extend": false,
    "enable_thinking": false,
    "watermark": false
  }'
```

### Edit with a reference URL

```bash
curl "https://api.uniall.ai/v1/images/edits" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "Turn the cup blue and keep the rest unchanged",
    "image": ["https://images.example.com/reference.png"],
    "n": 1,
    "size": "1024x1024"
  }'
```

The same JSON body can be sent to `/v1/images/generations`: including `image` selects editing. Reference-array order is preserved.

### Edit with a local file

```bash
curl "https://api.uniall.ai/v1/images/edits" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -F "model=qwen-image-2.1-pro" \
  -F "prompt=Turn the cup blue and keep the rest unchanged" \
  -F "image[]=@reference.png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "seed=0" \
  -F "enable_thinking=false"
```

Repeat `-F "image[]=@another.png"` for more references. Form options use integer strings and `true` / `false`; let cURL set the multipart Content-Type.

### Response

Generation and editing return the same shape. Read image URLs from `data[].url`.

```json
{
  "created": 1792627200,
  "data": [
    {
      "url": "https://images.example.com/result.png"
    }
  ]
}
```

## Bailian native API {/* #bailian-native */}

Use exactly one `user` message containing one `text` item. Add `image` items for editing; omit them for text-to-image.

### Generate

```bash
curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0",
    "input": {
      "messages": [{
        "role": "user",
        "content": [{"text": "A blue ceramic cup on a wooden table"}]
      }]
    },
    "parameters": {
      "n": 1,
      "size": "1024*1024",
      "seed": 0,
      "prompt_extend": false,
      "enable_thinking": false,
      "watermark": false
    }
  }'
```

### Edit

```bash
curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "input": {
      "messages": [{
        "role": "user",
        "content": [
          {"image": "https://images.example.com/reference.png"},
          {"text": "Turn the cup blue and keep the rest unchanged"}
        ]
      }]
    },
    "parameters": {"n": 1, "size": "1024*1024"}
  }'
```

### Response

Read image URLs from `output.choices[].message.content[].image`.

```json
{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://images.example.com/result.png"
            }
          ]
        }
      }
    ]
  },
  "request_id": "req_example"
}
```

## Limits

- Output area: 262,144–4,194,304 pixels (512²–2048²); aspect ratio: 1:8–8:1. This is an area limit, not a 2048-pixel limit on each edge. Standard 4K sizes such as `3840x2160` exceed it.
- References: up to 10 MB each; per-model counts are listed above.
- Results are PNG images. For transparent output on 2.1 models, request a transparent background in the prompt.
- Streaming, mask editing and Base64 output are unsupported. Omit `quality`, `output_format` and `operation`.

Requests can take tens of seconds. After a timeout, check request records before resubmitting. Save returned images before their URLs expire.

## Request errors

For HTTP 400, check required fields, model-specific options, reference counts and size limits. For HTTP 401, check the Bearer key. `/v1/images/edits` requires at least one reference image.