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

> ## Agent Instructions
> Authenticate every request with your API key in the `X-API-Key` header or `Authorization: Bearer`. Keys start with `sk-nunchux-`.
> Image generation is synchronous: the image is in the response.
> Video generation is asynchronous: submit the job, poll its task until it reaches a terminal status, then download the output promptly, because output URLs expire.

# Qwen Image

> Generate and edit images with Alibaba Cloud's Qwen Image 3.0 models in one synchronous call.

# Qwen Image

Qwen Image 3.0 is Alibaba Cloud's image model. It generates an image from a text prompt, and it edits up to three images that you send with the prompt. The call is synchronous: one POST returns the image in the response, so there is nothing to poll. The request and response shapes mirror Alibaba Cloud's own API.

<Note>
  Best for

  * Generating and editing on one endpoint, with one model ID.
  * Edits that combine up to three input images.
  * Batches. One request returns up to six images.
</Note>

## Models

| Model | Model ID | Tasks | Sizes | Input images | Images per request |
| - | - | - | - | - | - |
| Qwen Image 3.0 | `qwen-image-3.0` | Generate, edit | `1K`, `2K` | Up to 3 | 1 to 6 |
| Qwen Image 3.0 Pro | `qwen-image-3.0-pro` | Generate, edit | `1K`, `2K` | Up to 3 | 1 to 6 |

Each model uses one ID for both tasks. The items in the message select the task. A text item alone generates an image. Image items before the text item edit those images.

Qwen Image 3.0 Pro is the higher grade of Qwen Image 3.0, with the same request shape and the same limits. It costs more per image. Use Qwen Image 3.0 while you iterate, and Qwen Image 3.0 Pro for the final image.

## Endpoints

The base URL is `https://api.nunchux.ai`.

| Step | Method | Path |
| - | - | - |
| Generate or edit | `POST` | `/v1/alibaba/services/aigc/multimodal-generation/generation` |

There is no poll route. The image is in the response.

[Wan](/partner-models/wan) and [HappyHorse](/partner-models/happyhorse) use the same `/v1/alibaba` route family, with an asynchronous video route.

## Request

Send your API key in the `X-API-Key` header. See [Authentication](/authentication). Set `Content-Type: application/json`.

<ParamField body="model" type="string" required>
  The model ID from the table above: `qwen-image-3.0` or `qwen-image-3.0-pro`.
</ParamField>

<ParamField body="input" type="object" required>
  The prompt and the input images.

  <Expandable title="properties">
    <ParamField body="messages" type="array" required>
      One message, with `role` set to `user`.

      <Expandable title="message properties">
        <ParamField body="role" type="string" required>
          Must be `user`.
        </ParamField>

        <ParamField body="content" type="array" required>
          The input images first, then the prompt.

          * `{"image": "..."}`: an input image, as a URL or a data URI. Edits only. Up to 3 items. The provider fetches a URL, so it must be reachable from the internet.
          * `{"text": "..."}`: the prompt. One item, after the images. On an edit, say what must change and what must stay.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parameters" type="object">
  The generation controls.

  <Expandable title="properties">
    <ParamField body="size" type="string">
      The output size, as `width*height` in pixels, for example `1328*1328`. The output area selects the price tier. A size up to 2,250,000 pixels is billed at the `1K` tier. A larger size is billed at the `2K` tier. Alibaba Cloud documents sizes from `512*512` to `2048*2048`.

      If you omit it, the image is `2048*2048` and is billed at the `2K` tier.
    </ParamField>

    <ParamField body="n" type="integer" default={1}>
      The number of images. Range: 1 to 6. Each image is billed.
    </ParamField>

    <ParamField body="prompt_extend" type="boolean" default={true}>
      When `true`, Alibaba Cloud rewrites the prompt into a more detailed one before the image renders, and `output.rewrite_status` is `success`. Set it to `false` to render your prompt as written. `output.rewrite_status` is then `not_use`.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Common sizes

  | Shape | `1K` tier | `2K` tier |
  | - | - | - |
  | 1:1 | `1328*1328` | `2048*2048` |
  | 16:9 | `1664*928` | `2048*1152` |
  | 9:16 | `928*1664` | `1152*2048` |
  | 4:3 | `1472*1104` | `2048*1536` |
  | 3:4 | `1104*1472` | `1536*2048` |
</Note>

A minimal request body:

```json theme={"system"}
{
  "model": "qwen-image-3.0",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [{ "text": "a paper lantern floating over a quiet canal at night" }]
      }
    ]
  },
  "parameters": { "size": "1328*1328", "n": 1 }
}
```

## Response

The response is Alibaba Cloud's own JSON body. Each image is a URL in `output.choices[].message.content[]`.

<ResponseField name="output" type="object" required>
  The result.

  <Expandable title="properties">
    <ResponseField name="choices" type="array" required>
      The generated images.

      <Expandable title="item properties">
        <ResponseField name="message.content[].image" type="string">
          The URL of the image. It is signed and expires after 24 hours. Download the image as soon as you receive it.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rewrite_status" type="string">
      `success` when Alibaba Cloud rewrote the prompt, `not_use` when `prompt_extend` was `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  What the request produced: `output_width`, `output_height`, `output_image_count`, `output_image_type` (the size tier), and `input_image_count`. Nunchux bills from these values.
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Alibaba Cloud's identifier for the request.
</ResponseField>

```json theme={"system"}
{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [{ "type": "image", "image": "https://<signed-url>" }]
        }
      }
    ],
    "rewrite_status": "success"
  },
  "usage": {
    "input_image_count": 0,
    "input_image_type": "qima_input_1k",
    "output_height": 1328,
    "output_image_count": 1,
    "output_image_type": "qima_output_1k",
    "output_width": 1328
  },
  "request_id": "19a65aa2-7483-9dc9-85ab-92f349127856"
}
```

## Example

### Generate

<CodeGroup>
  ```bash cURL theme={"system"}
  # Synchronous: one POST returns the image URL. There is no polling.
  # The URL is at output.choices[0].message.content[0].image and expires after 24 hours.
  url=$(curl -s https://api.nunchux.ai/v1/alibaba/services/aigc/multimodal-generation/generation \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $NUNCHUX_API_KEY" \
    -d '{
      "model": "qwen-image-3.0",
      "input": {
        "messages": [
          {
            "role": "user",
            "content": [{"text": "a paper lantern floating over a quiet canal at night"}]
          }
        ]
      },
      "parameters": {"size": "1328*1328", "n": 1}
    }' | jq -r '.output.choices[0].message.content[0].image')
  curl -s -o output.png "$url"
  ```

  ```python Python theme={"system"}
  import os
  import requests

  response = requests.post(
      "https://api.nunchux.ai/v1/alibaba/services/aigc/multimodal-generation/generation",
      headers={
          "Content-Type": "application/json",
          "X-API-Key": os.environ["NUNCHUX_API_KEY"],
      },
      json={
          "model": "qwen-image-3.0",
          "input": {
              "messages": [
                  {
                      "role": "user",
                      "content": [{"text": "a paper lantern floating over a quiet canal at night"}],
                  }
              ]
          },
          "parameters": {"size": "1328*1328", "n": 1},
      },
  )

  # The URL expires after 24 hours, so download the image at once.
  url = response.json()["output"]["choices"][0]["message"]["content"][0]["image"]
  with open("output.png", "wb") as f:
      f.write(requests.get(url).content)
  ```

  ```javascript JavaScript theme={"system"}
  import { writeFile } from "node:fs/promises";

  const response = await fetch(
    "https://api.nunchux.ai/v1/alibaba/services/aigc/multimodal-generation/generation",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.NUNCHUX_API_KEY,
      },
      body: JSON.stringify({
        model: "qwen-image-3.0",
        input: {
          messages: [
            {
              role: "user",
              content: [{ text: "a paper lantern floating over a quiet canal at night" }],
            },
          ],
        },
        parameters: { size: "1328*1328", n: 1 },
      }),
    }
  );
  const data = await response.json();

  // The URL expires after 24 hours, so download the image at once.
  const url = data.output.choices[0].message.content[0].image;
  await writeFile("output.png", Buffer.from(await (await fetch(url)).arrayBuffer()));
  ```
</CodeGroup>

### Edit

Put the input images before the prompt. Replace the example URL with an image that the provider can fetch.

<CodeGroup>
  ```bash cURL theme={"system"}
  url=$(curl -s https://api.nunchux.ai/v1/alibaba/services/aigc/multimodal-generation/generation \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $NUNCHUX_API_KEY" \
    -d '{
      "model": "qwen-image-3.0-pro",
      "input": {
        "messages": [
          {
            "role": "user",
            "content": [
              {"image": "https://example.com/street.png"},
              {"text": "make it night and add warm lantern light"}
            ]
          }
        ]
      },
      "parameters": {"size": "1328*1328", "n": 1}
    }' | jq -r '.output.choices[0].message.content[0].image')
  curl -s -o output.png "$url"
  ```

  ```python Python theme={"system"}
  import os
  import requests

  response = requests.post(
      "https://api.nunchux.ai/v1/alibaba/services/aigc/multimodal-generation/generation",
      headers={
          "Content-Type": "application/json",
          "X-API-Key": os.environ["NUNCHUX_API_KEY"],
      },
      json={
          "model": "qwen-image-3.0-pro",
          "input": {
              "messages": [
                  {
                      "role": "user",
                      "content": [
                          {"image": "https://example.com/street.png"},
                          {"text": "make it night and add warm lantern light"},
                      ],
                  }
              ]
          },
          "parameters": {"size": "1328*1328", "n": 1},
      },
  )

  url = response.json()["output"]["choices"][0]["message"]["content"][0]["image"]
  with open("output.png", "wb") as f:
      f.write(requests.get(url).content)
  ```
</CodeGroup>

## Tips

* Set `size` explicitly. An omitted size renders at `2048*2048` and is billed at the `2K` tier.
* Keep a size at or under 2,250,000 pixels when `1K` is enough. The common `1K` sizes above all qualify.
* Leave `prompt_extend` on for short prompts. Turn it off when the prompt is already detailed, or when you need the exact words rendered.
* On an edit, put the images first and the prompt last. When you send several images, say which element comes from which image.
* Download each image on receipt. The URL expires after 24 hours.

## Errors and limits

* `n` above 6 returns a 400 with the code `invalid_request`. So does a request with more than 3 input images. A refused request is not charged.
* An error from Alibaba Cloud returns Alibaba Cloud's own body, with `code`, `message` and `request_id`, for example `InvalidParameter`. The charge is refunded in full.
* Qwen Image is priced per output image at the rate of its size tier, plus a small fee per input image. The rates are on the [pricing page](https://nunchux.ai/pricing). Nunchux deducts the credits when it sends the request. When Alibaba Cloud returns fewer images than you asked for, Nunchux refunds the difference. See [Credits and pricing](/credits-pricing).
* A Qwen Image call counts toward your requests per minute. It does not take a simultaneous-job slot. See [Rate limits](/rate-limits).

The full error contract and the per-plan caps are on the [Errors](/errors) and [Rate limits](/rate-limits) pages. How every partner model bills and refunds is on the [Partner models overview](/partner-models/overview).


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