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

# Qwen Image Generation and Editing API Reference

> The Qwen Image Generation and Editing model supports both text-to-image (T2I) and image-to-image/image editing (I2I). It can generate images directly from text prompts or edit images based on reference images combined with editing instructions. Supports both the OpenAI-compatible and DashScope protocols.

## Model overview <span id="en-6740266-model-title" /> <span id="en-6740266-model-overview" />

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}><colgroup><col style={{ width: "24%" }} /><col style={{ width: "38%" }} /><col style={{ width: "38%" }} /></colgroup><thead><tr><th><p><strong>Model</strong></p></th><th><p><strong>Description</strong></p></th><th><p><strong>Output image specifications</strong></p></th></tr></thead><tbody><tr><td><p>qwen-image-3.0-pro</p></td><td><p>Qwen Image Generation and Editing 3.0 model that supports both text-to-image (T2I) and image-to-image/image editing (I2I).</p></td><td rowSpan={3}><p>Image resolution:</p><ul><li><p><strong>Text-to-image (T2I)</strong>: Total pixels must be between 512\*512 and 2048\*2048.</p></li><li><p><strong>Image-to-image (I2I)</strong>: Total pixels must be between 512\*512 and 2048\*2048.</p></li><li><p><strong>Default</strong>: When <code>size</code> is not specified, the model automatically recommends a resolution based on the prompt.</p></li></ul><p>Image format: PNG</p></td></tr><tr><td><p>qwen-image-3.0</p></td><td><p>Qwen Image Generation and Editing 3.0 standard model that supports both text-to-image (T2I) and image-to-image/image editing (I2I). Balances quality and speed.</p></td></tr><tr><td><p>qwen-image-2.1-pro</p></td><td><p>Qwen Image Generation and Editing 2.1 Pro model. Image-to-image/image editing (I2I) supports up to 10 reference images. It can also automatically decide whether to output a standard image or an image with a transparent (alpha) channel based on the prompt description.</p></td></tr></tbody></table>

## Availability <span id="1fd78afa5brlj" /> <span id="en-6740266-prereq" />

The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.

- [Select a model](/en/model-studio/video-generate-edit-model): Verify that the model is available in your target region.
- <strong>Select a URL</strong>: Choose the endpoint URL that matches your model's region. Both HTTP and DashScope SDK URLs are supported.
- <strong>Configure an API key</strong>: Get an [API key](/en/model-studio/get-api-key) for the region, and then [configure the API key as an environment variable](/en/model-studio/get-api-key).
- <strong>Install the SDK</strong>: To make API calls with the SDK, [install the DashScope SDK](/en/model-studio/install-sdk).

<Note>
  The sample code in this topic applies to the <strong>Singapore</strong> region.
</Note>

<Tip>
  Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. <strong>The new dedicated domains deliver superior performance and higher stability for inference requests</strong>. We recommend migrating to the new domains:

  - China (Beijing): from `https://dashscope.aliyuncs.com` to `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`
  - Singapore: from `https://dashscope-intl.aliyuncs.com` to `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`

  `{WorkspaceId}` is your workspace ID, which can be found on the <strong>Workspace Details</strong> page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.
</Tip>

## Access methods <span id="en-6740266-access-title" />

Qwen Image Generation and Editing offers three access methods with identical model capabilities. Choose the one that fits your application:

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}><colgroup><col style={{ width: "28%" }} /><col style={{ width: "72%" }} /></colgroup><thead><tr><th><p><strong>Access method</strong></p></th><th><p><strong>When to use</strong></p></th></tr></thead><tbody><tr><td><p><a href="/en/model-studio/qwen-image-generation-and-editing-api-reference#en-6740266-openai-title">OpenAI-compatible</a></p></td><td><p>Applications already built on the OpenAI Images protocol or the OpenAI SDK. Switch <code>base\_url</code> and <code>model</code> to migrate. Synchronous calls only. Image input supports both public URL and Base64.</p></td></tr><tr><td><p><a href="/en/model-studio/qwen-image-generation-and-editing-api-reference#en-6740266-sync-title">DashScope synchronous</a></p></td><td><p>Recommended. Full feature coverage, including both public URL and Base64 image input.</p></td></tr><tr><td><p><a href="/en/model-studio/qwen-image-generation-and-editing-api-reference#en-6740266-async-title">DashScope asynchronous</a></p></td><td><p>Batch generation, or when you do not want to hold a connection open. Submit a task and poll for results with <code>task\_id</code>.</p></td></tr></tbody></table>

## OpenAI-compatible <span id="en-6740266-openai-title" />

If your application is already built on the OpenAI Images protocol or the OpenAI SDK, you can call Qwen Image Generation and Editing through the OpenAI-compatible mode without changing your request structure. Text-to-image (T2I) and image-to-image/image editing (I2I) share the same endpoint: <strong>omit</strong> `image` <strong>for T2I, and provide</strong> `image` <strong>for I2I</strong>.

<Note>
  The OpenAI-compatible mode is a <strong>synchronous, non-streaming</strong> endpoint. Image editing uses the `image` extension field on `/images/generations`. It does <strong>not</strong> use the multipart file upload format of the official OpenAI `/images/edits` endpoint. The following are not yet supported: asynchronous calls, streaming output, partial images, `/images/edits`, multipart, and mask. Passing `response_format=b64_json` does not raise an error, but it is ignored and the response still contains image URLs. For asynchronous calls, use [DashScope asynchronous](/en/model-studio/qwen-image-generation-and-editing-api-reference#en-6740266-async-title).
</Note>

### URL <span id="en-6740266-openai-url-title" />

<Tabs>
  <Tab title="Singapore">
    HTTP endpoint: `POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>

  <Tab title="US (Virginia)">
    HTTP endpoint: `POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>

  <Tab title="China (Beijing)">
    HTTP endpoint: `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>

  <Tab title="China (Hong Kong)">
    HTTP endpoint: `POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>

  <Tab title="Germany (Frankfurt)">
    HTTP endpoint: `POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>

  <Tab title="Japan (Tokyo)">
    HTTP endpoint: `POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations`

    base\_url for SDK calls: `https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1`
  </Tab>
</Tabs>

Replace `{WorkspaceId}` with your actual [workspace ID](/en/model-studio/regions#h2_migrate_domain).

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ### Request parameters <span id="en-6740266-openai-req-params-title" />

        #### Headers <span id="en-6740266-openai-headers-h4" />

        <strong>Content-Type</strong> `string` <strong>(Required)</strong>

        The content type of the request. Must be `application/json`.

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        #### Request body <span id="en-6740266-openai-body-h4" />

        Unlike the DashScope protocol, the OpenAI-compatible mode places <strong>all parameters at the top level</strong> of the request body. There is no `input` or `parameters` nesting.

        <strong>model</strong> `string` <strong>(Required)</strong>

        The model name. Available values: `qwen-image-3.0-pro`, `qwen-image-3.0`, and `qwen-image-2.1-pro`.

        <strong>prompt</strong> `string` <strong>(Required)</strong>

        The positive prompt that describes the image content, style, and composition you want to generate or edit. Both Chinese and English are supported. Recommended maximum: 4,500 tokens. Cannot be an empty string.

        <strong>image</strong> `string`<strong> or </strong>`array` (Optional)

        The URL or Base64 encoded data of the input image. Omit this parameter for text-to-image (T2I). Provide it for image-to-image (I2I), where qwen-image-2.1-pro supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. Pass a string for a single image, or an array of strings for multiple images. When multiple images are provided, the order is defined by the array sequence.

        <strong>Note</strong>: `null` and empty arrays are rejected with a 400 error.

        <strong>Image requirements:</strong>

        - Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
        - Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
        - Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
        - Image size: Up to 10 MB.

        <strong>Supported input formats</strong>

        1. Public URL: HTTP and HTTPS protocols are supported.
        2. Base64 encoding: Format is `data:{MIME_type};base64,{base64_data}`.

        <strong>n</strong> `integer` (Optional)

        The number of output images. Value range: 1 to 6. Default: 1. Must be an integer. A string value such as `"1"` returns a 400 error.

        <strong>size</strong> `string` (Optional)

        The output image resolution in the format `widthxheight`, for example `"1024x1024"`. You can also pass `auto`. If not specified, the model automatically recommends a resolution based on the prompt.

        <Warning>
          The OpenAI protocol uses the <strong>letter</strong> `x` <strong>as the separator</strong> (`1024x1024`), not the asterisk `*` used by the DashScope protocol (`1024*1024`). Update this value when migrating from DashScope.
        </Warning>

        - <strong>Text-to-image (T2I)</strong>: Pixel area from 512x512 to 2048x2048. Aspect ratio: 1:8 to 8:1.
        - <strong>Image-to-image (I2I)</strong>: Pixel area from 512x512 to 2048x2048. Aspect ratio: 1:8 to 8:1.

        <strong>negative\_prompt</strong> `string` (Optional)

        The negative prompt that describes content you do not want to appear in the image. Only the qwen-image-3.0 series supports this parameter.

        <strong>seed</strong> `integer` (Optional)

        The random seed. Value range: `[0, 2147483647]`. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.

        <strong>prompt\_extend</strong> `boolean` (Optional)

        Whether to enable intelligent prompt rewriting. Default: `true` (recommended). When enabled, the model optimizes the positive prompt using the method specified by `prompt_extend_mode`, which significantly improves results for simple descriptions.

        <strong>prompt\_extend\_mode</strong> `string` (Optional)

        The prompt rewriting method. Default: `direct`. Options:

        - `direct`: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
        - `agent`: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing `agent` for image-to-image (I2I) will return a 400 error.

        <strong>enable\_thinking</strong> `boolean` (Optional)

        Enables thinking mode. The default is `true`. This enhances model reasoning to improve image quality, but increases generation time. It requires `prompt_extend=true`. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.

        <strong>watermark</strong> `boolean` (Optional)

        Whether to add a watermark. Default: `false`.

        <Note>
          `image`, `negative_prompt`, `seed`, `prompt_extend`, `prompt_extend_mode`, `enable_thinking`, and `watermark` are Model Studio extension fields, not official OpenAI parameters. For raw HTTP requests, place them at the top level of the request body. When using an OpenAI SDK, pass them through `extra_body`.
        </Note>
      </td>

      <td>
        <CodeGroup>
          ```bash Text-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --data '{
              "model": "qwen-image-3.0-pro",
              "prompt": "A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads '\''Il Messaggero'\'' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street'\''s end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere.",
              "size": "1024x1024",
              "n": 1,
              "prompt_extend": true
          }'
          ```

          ```bash Image-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --data '{
              "model": "qwen-image-3.0-pro",
              "prompt": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere.",
              "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png",
              "size": "1024x1024",
              "n": 1,
              "prompt_extend": true
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ### Response parameters <span id="en-6740266-openai-resp-title" />

        <strong>created</strong> `integer`

        The Unix timestamp, in seconds, when the response was created.

        <strong>data</strong> `array`

        The list of generated results. When `n` is greater than 1, the array contains multiple elements.

        <Accordion title="Properties" defaultOpen>
          <strong>url</strong> `string`

          The URL of the generated image in PNG format. <strong>The link is valid for 24 hours.</strong> Download and save the image promptly.
        </Accordion>

        <strong>usage</strong> `object`

        The resource usage of this call. Only returned on success. These are <strong>image input and output metering fields, not token usage</strong>.

        <Accordion title="Properties" defaultOpen>
          <Tabs>
            <Tab title="qwen-image-3.0 series">
              <strong>output\_width</strong> `integer`

              The width of the final output image in pixels.

              <strong>output\_height</strong> `integer`

              The height of the final output image in pixels.

              <strong>input\_image\_count</strong> `integer`

              The number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).

              <strong>input\_image\_type</strong> `string`

              The input image billing tier. Determined by the output resolution pixel area: `qima_input_1k` if area ≤ 2,250,000, or `qima_input_2k` if area > 2,250,000.

              <strong>output\_image\_count</strong> `integer`

              The actual number of output images returned.

              <strong>output\_image\_type</strong> `string`

              The output image billing tier. Determined by the output resolution pixel area: `qima_output_1k` if area ≤ 2,250,000, or `qima_output_2k` if area > 2,250,000.
            </Tab>

            <Tab title="qwen-image-2.1-pro">
              <strong>image\_count</strong> `integer`

              The number of images generated by the model.

              <strong>width</strong> `integer`

              The width of the generated image in pixels.

              <strong>height</strong> `integer`

              The height of the generated image in pixels.
            </Tab>
          </Tabs>
        </Accordion>

        <strong>error</strong> `object`

        The error details. Only returned for failed requests.

        <Accordion title="Properties" defaultOpen>
          <strong>message</strong> `string`

          Detailed error message.

          <strong>type</strong> `string`

          The error type, such as `invalid_request_error`.

          <strong>param</strong> `string`

          The name of the parameter that caused the error, or `null` when the error cannot be attributed to a specific parameter.

          <strong>code</strong> `string`

          Error code. See [Error codes](/en/model-studio/error-code).
        </Accordion>

        <Note>
          Unlike the DashScope protocol, the OpenAI-compatible mode <strong>does not return</strong> `request_id` in the response body. The unique request identifier is returned in the `x-request-id` HTTP response header. With the OpenAI Python SDK, read `response._request_id` on success and `APIStatusError.request_id` on failure. Include this identifier when reporting an issue.
        </Note>
      </td>

      <td>
        <Tabs>
          <Tab title="Success">
            Image URLs are retained for only 24 hours and then automatically purged. Save generated images promptly.

            <CodeGroup>
              ```json qwen-image-3.0 series
              {
                  "created": 1788339600,
                  "data": [
                      {
                          "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                      }
                  ],
                  "usage": {
                      "output_height": 1024,
                      "output_width": 1024,
                      "input_image_count": 0,
                      "input_image_type": "qima_input_1k",
                      "output_image_count": 1,
                      "output_image_type": "qima_output_1k"
                  }
              }
              ```

              ```json qwen-image-2.1-pro
              {
                  "created": 1788339600,
                  "data": [
                      {
                          "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                      }
                  ],
                  "usage": {
                      "image_count": 1,
                      "width": 1024,
                      "height": 1024
                  }
              }
              ```
            </CodeGroup>
          </Tab>

          <Tab title="Error">
            If the request fails, the response contains an `error` object whose `code` and `message` fields identify the cause. See [Error codes](/en/model-studio/error-code) for troubleshooting.

            ```json
            {
                "error": {
                    "message": "Field 'prompt' is required",
                    "type": "invalid_request_error",
                    "param": null,
                    "code": "InvalidParameter"
                }
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

### SDK <span id="en-6740266-openai-sdk-title" />

Install or upgrade the OpenAI Python SDK first:

```bash
pip install -U openai
```

<Tip>
  Image generation can take a long time. Set an explicit, generous client timeout. For multi-image output (a larger `n`) or concurrent requests, start at 600 seconds so the client does not disconnect early.
</Tip>

<CodeGroup>
  ```python Text-to-image expandable
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
      timeout=600.0,
  )

  response = client.images.generate(
      model="qwen-image-3.0-pro",
      prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads 'Il Messaggero' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street's end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere.",
      size="1024x1024",
      n=1,
      # All parameters above are official OpenAI parameters. Extension fields such as
      # image and prompt_extend go through extra_body. See the I2I example.
  )

  for item in response.data:
      print(item.url)
  print(f"request_id: {response._request_id}")
  ```

  ```python Image-to-image expandable
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
      timeout=600.0,
  )

  response = client.images.generate(
      model="qwen-image-3.0-pro",
      prompt="Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.",
      size="1024x1024",
      n=1,
      extra_body={
          # A single image can also be passed as a plain string. Base64 is also accepted:
          # data:{MIME_type};base64,{base64_data}
          "image": [
              "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
          ],
          "prompt_extend": True,
      },
  )

  for item in response.data:
      print(item.url)
  print(f"request_id: {response._request_id}")
  ```

  ```python Reading request_id expandable
  import os
  from openai import OpenAI, APIStatusError

  client = OpenAI(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
      timeout=600.0,
  )

  try:
      response = client.images.generate(
          model="qwen-image-3.0-pro",
          prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere.",
      )
      print(response.data[0].url)
  except APIStatusError as exc:
      print(f"status_code: {exc.status_code}")
      print(f"request_id: {exc.request_id}")
      print(exc)
  ```
</CodeGroup>

## DashScope synchronous API (recommended) <span id="en-6740266-sync-title" /> <span id="en-6740266-sync" />

### HTTP <span id="en-6740266-http-title" /> <span id="en-6740266-http" />

<Tabs>
  <Tab title="Singapore">
    `POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>

  <Tab title="US (Virginia)">
    `POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>

  <Tab title="China (Beijing)">
    `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>

  <Tab title="China (Hong Kong)">
    `POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>

  <Tab title="Germany (Frankfurt)">
    `POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>

  <Tab title="Japan (Tokyo)">
    `POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
  </Tab>
</Tabs>

Replace `{WorkspaceId}` with your actual [workspace ID](/en/model-studio/regions#h2_migrate_domain).

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Request parameters <span id="en-6740266-req-params-h4" /> <span id="en-6740266-req-section" />

        ##### Headers <span id="en-6740266-headers-h5" />

        <strong>Content-Type</strong> `string` <strong>(Required)</strong>

        The content type of the request. Must be `application/json`.

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        ##### Request body <span id="en-6740266-body-h5" />

        <strong>model</strong> `string` <strong>(Required)</strong>

        The model name. Available values: `qwen-image-3.0-pro`, `qwen-image-3.0`, and `qwen-image-2.1-pro`.

        <strong>input</strong> `object` <strong>(Required)</strong>

        The input parameter object, which contains the following fields:

        <Accordion title="Properties" defaultOpen>
          <strong>messages</strong> `array` <strong>(Required)</strong>

          The request content array. <strong>Only single-round conversations are supported</strong>, so the array must contain <strong>exactly one object</strong> with `role` and `content` properties.

          <Accordion title="Properties" defaultOpen>
            <strong>role</strong>`string` <strong>(Required)</strong>

            The role of the message sender. Must be set to `user`.

            <strong>content</strong>`array` <strong>(Required)</strong>

            The message content array, with different combinations depending on the use case:

            - <strong>Text-to-image (T2I)</strong>: Contains only one `{"text": "..."}` object.
            - <strong>Image-to-image (I2I)</strong>: qwen-image-2.1-pro contains 1-10 `{"image": "..."}` objects, the qwen-image-3.0 series contains 1-3, and 1 `{"text": "..."}` object.

            <Accordion title="Properties" defaultOpen>
              <strong>image</strong> `string` <strong>(Required for I2I)</strong>

              The URL or Base64 encoded data of the input image. In I2I scenarios, qwen-image-2.1-pro supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. When multiple images are provided, the order is defined by the array sequence.

              <strong>Image requirements:</strong>

              - Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
              - Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
              - Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
              - Image size: Up to 10 MB.

              <strong>Supported input formats</strong>

              1. Public URL: HTTP and HTTPS protocols are supported.
              2. Base64 encoding: Format is `data:{MIME_type};base64,{base64_data}`.

              <strong>text</strong>`string`<strong>(Required)</strong>

              The positive prompt that describes the image content, style, and composition you want to generate or edit. Both Chinese and English are supported. Recommended maximum: 4,500 tokens.

              <strong>Note</strong>: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.
            </Accordion>
          </Accordion>
        </Accordion>

        <strong>parameters</strong> `object` (Optional)

        Additional parameters to control image generation.

        <Accordion title="Properties" defaultOpen>
          <strong>prompt\_extend</strong> `boolean` (Optional)

          Whether to enable intelligent prompt rewriting. Default: `true` (recommended). When enabled, the model optimizes the positive prompt using the method specified by `prompt_extend_mode`, which significantly improves results for simple descriptions.

          <strong>prompt\_extend\_mode</strong> `string` (Optional)

          The prompt rewriting method. Default: `direct`. Options:

          - `direct`: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
          - `agent`: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing `agent` for image-to-image (I2I) will return a 400 error.

          <strong>enable\_thinking</strong> `boolean` (Optional)

          Enables thinking mode. The default is `true`. This enhances model reasoning to improve image quality, but increases generation time. It requires `prompt_extend=true`. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.

          <strong>n</strong> `integer` (Optional)

          The number of output images. Value range: 1 to 6. Default: 1.

          <strong>size</strong> `string` (Optional)

          The output image resolution in the format `width*height`, for example `"1024*1024"`. If not specified, the model automatically recommends a resolution based on the prompt.

          - <strong>Text-to-image (T2I)</strong>: Pixel area from 512\*512 to 2048\*2048. Aspect ratio: 1:8 to 8:1.
          - <strong>Image-to-image (I2I)</strong>: Pixel area from 512\*512 to 2048\*2048. Aspect ratio: 1:8 to 8:1.

          <strong>negative\_prompt</strong> `string` (Optional)

          The negative prompt that describes content you do not want to appear in the image. Only the qwen-image-3.0 series supports this parameter.

          <strong>seed</strong> `integer` (Optional)

          The random seed. Value range: `[0, 2147483647]`. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.

          <strong>watermark</strong> `boolean` (Optional)

          Whether to add a watermark. Default: `false`.
        </Accordion>
      </td>

      <td>
        <CodeGroup>
          ```bash Text-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --data '{
              "model": "qwen-image-3.0-pro",
              "input": {
                  "messages": [
                      {
                          "role": "user",
                          "content": [
                              {
                                  "text": "A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads '\''Il Messaggero'\'' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street'\''s end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere."
                              }
                          ]
                      }
                  ]
              },
              "parameters": {
                  "prompt_extend": true
              }
          }'
          ```

          ```bash Image-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --data '{
              "model": "qwen-image-3.0-pro",
              "input": {
                  "messages": [
                      {
                          "role": "user",
                          "content": [
                              {
                                  "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                              },
                              {
                                  "text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                              }
                          ]
                      }
                  ]
              },
              "parameters": {
                  "prompt_extend": true
              }
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Response parameters <span id="en-6740266-resp-h4" /> <span id="en-6740266-resp-section" />

        <strong>output</strong> `object`

        Contains the model generation results.

        <Accordion title="Properties" defaultOpen>
          <strong>rewrite\_status</strong> `string`

          The prompt rewriting status. The value depends on whether rewriting was enabled in the request and the result of the rewrite.

          <strong>choices</strong> `array`

          The list of result options.

          <Accordion title="Properties" defaultOpen>
            <strong>finish\_reason</strong> `string`

            The reason why the task stopped. The value is `stop` when the task completes normally.

            <strong>message</strong> `object`

            The message returned by the model.

            <Accordion title="Properties" defaultOpen>
              <strong>role</strong>`string`

              The role of the message. Fixed as `assistant`.

              <strong>content</strong>`array`

              The message content containing the generated image information.

              <Accordion title="Properties" defaultOpen>
                <strong>image</strong> `string`

                The URL of the generated image in PNG format. <strong>The link is valid for 24 hours</strong>. Please download and save the image promptly.
              </Accordion>
            </Accordion>
          </Accordion>
        </Accordion>

        <strong>usage</strong> `object`

        The resource usage of this call. Only returned on success. These are <strong>image input and output metering fields, not token usage</strong>.

        <Accordion title="Properties" defaultOpen>
          <Tabs>
            <Tab title="qwen-image-3.0 series">
              <strong>output\_width</strong> `integer`

              The width of the final output image in pixels.

              <strong>output\_height</strong> `integer`

              The height of the final output image in pixels.

              <strong>input\_image\_count</strong> `integer`

              The number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).

              <strong>input\_image\_type</strong> `string`

              The input image billing tier. Determined by the output resolution pixel area: `qima_input_1k` if area ≤ 2,250,000, or `qima_input_2k` if area > 2,250,000.

              <strong>output\_image\_count</strong> `integer`

              The actual number of output images returned.

              <strong>output\_image\_type</strong> `string`

              The output image billing tier. Determined by the output resolution pixel area: `qima_output_1k` if area ≤ 2,250,000, or `qima_output_2k` if area > 2,250,000.
            </Tab>

            <Tab title="qwen-image-2.1-pro">
              <strong>image\_count</strong> `integer`

              The number of images generated by the model.

              <strong>width</strong> `integer`

              The width of the generated image in pixels.

              <strong>height</strong> `integer`

              The height of the generated image in pixels.
            </Tab>
          </Tabs>
        </Accordion>

        <strong>request\_id</strong> `string`

        Unique request identifier for tracing and troubleshooting.

        <strong>code</strong> `string`

        Error code. Returned only for failed requests. See [Error codes](/en/model-studio/error-code).

        <strong>message</strong> `string`

        Detailed error message. Returned only for failed requests. See [Error codes](/en/model-studio/error-code).
      </td>

      <td>
        <Tabs>
          <Tab title="Success">
            Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.

            <CodeGroup>
              ```json qwen-image-3.0 series
              {
                  "output": {
                      "choices": [
                          {
                              "finish_reason": "stop",
                              "message": {
                                  "content": [
                                      {
                                          "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                                      }
                                  ],
                                  "role": "assistant"
                              }
                          }
                      ]
                  },
                  "usage": {
                      "output_height": 1024,
                      "output_width": 1024,
                      "input_image_count": 1,
                      "input_image_type": "qima_input_1k",
                      "output_image_count": 1,
                      "output_image_type": "qima_output_1k"
                  },
                  "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
              }
              ```

              ```json qwen-image-2.1-pro
              {
                  "output": {
                      "choices": [
                          {
                              "finish_reason": "stop",
                              "message": {
                                  "content": [
                                      {
                                          "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                                      }
                                  ],
                                  "role": "assistant"
                              }
                          }
                      ]
                  },
                  "usage": {
                      "image_count": 1,
                      "width": 1024,
                      "height": 1024
                  },
                  "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
              }
              ```
            </CodeGroup>
          </Tab>

          <Tab title="Error">
            If the task fails, the response includes the error code and message. See [Error codes](/en/model-studio/error-code) for troubleshooting.

            ```json
            {
                "request_id": "31f808fd-8eef-9004-xxxxx",
                "code": "InvalidApiKey",
                "message": "Invalid API-key provided."
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

### SDK <span id="en-6740266-sdk-title" /> <span id="en-6740266-sdk" />

The following examples demonstrate how to call the API using Python and Java SDKs for image-to-image / image editing (I2I).

<CodeGroup dropdown>
  ```python Python expandable
  import os
  import base64
  import mimetypes
  import dashscope
  from dashscope import MultiModalConversation

  dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

  def encode_file(file_path):
      mime_type, _ = mimetypes.guess_type(file_path)
      if not mime_type or not mime_type.startswith("image/"):
          raise ValueError("Unsupported or unrecognized image format")
      with open(file_path, "rb") as image_file:
          encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
      return f"data:{mime_type};base64,{encoded_string}"

  # [Method 1] Use a public image URL
  image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"

  # [Method 2] Use a Base64-encoded image
  # image_url = encode_file("./your_image.png")

  response = MultiModalConversation.call(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      model="qwen-image-3.0-pro",
      messages=[{
          "role": "user",
          "content": [
              {"image": image_url},
              {"text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop."}
          ]
      }],
      prompt_extend=True
  )

  print(response)
  if response.status_code == 200:
      url = response.output.choices[0].message.content[0]["image"]
      print(f"Generated image URL: {url}")
  else:
      print(f"Error: {response.code} - {response.message}")
  ```

  ```java Java expandable
  import java.util.Arrays;
  import java.util.Base64;
  import java.util.Collections;
  import java.io.IOException;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.nio.file.Paths;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
  import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
  import com.alibaba.dashscope.common.MultiModalMessage;
  import com.alibaba.dashscope.common.Role;
  import com.alibaba.dashscope.utils.Constants;

  public class ImageEditExample {
      public static void main(String[] args) {
          Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

          // [Method 1] Use a public image URL
          String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";

          // [Method 2] Use a Base64-encoded image
          // String imageUrl = encodeFile("/path/to/your/image.png");

          MultiModalConversation conv = new MultiModalConversation();
          MultiModalMessage userMessage = MultiModalMessage.builder()
              .role(Role.USER.getValue())
              .content(Arrays.asList(
                  Collections.singletonMap("image", imageUrl),
                  Collections.singletonMap("text", "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.")
              ))
              .build();
          MultiModalConversationParam param = MultiModalConversationParam.builder()
              .apiKey(System.getenv("DASHSCOPE_API_KEY"))
              .model("qwen-image-3.0-pro")
              .messages(Arrays.asList(userMessage))
              .parameter("prompt_extend", true)
              .build();
          try {
              MultiModalConversationResult result = conv.call(param);
              System.out.println(result);
          } catch (Exception e) {
              e.printStackTrace();
          }
      }

      public static String encodeFile(String filePath) {
          Path path = Paths.get(filePath);
          if (!Files.exists(path)) {
              throw new IllegalArgumentException("File does not exist: " + filePath);
          }
          String mimeType = null;
          try {
              mimeType = Files.probeContentType(path);
          } catch (IOException e) {
              throw new IllegalArgumentException("Cannot detect file type: " + filePath);
          }
          if (mimeType == null || !mimeType.startsWith("image/")) {
              throw new IllegalArgumentException("Unsupported or unrecognized image format");
          }
          byte[] fileBytes = null;
          try {
              fileBytes = Files.readAllBytes(path);
          } catch (IOException e) {
              throw new IllegalArgumentException("Cannot read file content: " + filePath);
          }
          String encodedString = Base64.getEncoder().encodeToString(fileBytes);
          return "data:" + mimeType + ";base64," + encodedString;
      }
  }
  ```
</CodeGroup>

## DashScope asynchronous API <span id="en-6740266-async-title" /> <span id="en-6740266-async" />

In addition to the synchronous call described above, Qwen Image Generation and Editing also supports asynchronous calls. The asynchronous API shares the same request parameter structure as the synchronous API. You only need to add the `X-DashScope-Async: enable` header. After the service accepts the request, it returns a task ID (`task_id`), which you then use to poll the query API for the final result.

<Tip>
  The endpoint for the asynchronous API differs from the synchronous API. Use the endpoints in this section instead of the synchronous endpoint.
</Tip>

### HTTP <span id="en-6740266-async-http-title" /> <span id="en-6740266-async-http" />

Asynchronous calls use a two-step workflow:

1. <strong>Create a task to get a task ID</strong>: Send a request to create a task. The response contains a <strong>task ID (task\_id)</strong>.
2. <strong>Poll for results using the task ID</strong>: Use the task\_id to poll the task status until the task completes and the image URL is returned.

#### Step 1: Create a task to get a task ID <span id="en-6740266-async-step1-title" /> <span id="en-6740266-async-step1" />

<Tabs>
  <Tab title="Singapore">
    `POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>

  <Tab title="US (Virginia)">
    `POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>

  <Tab title="China (Beijing)">
    `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>

  <Tab title="China (Hong Kong)">
    `POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>

  <Tab title="Germany (Frankfurt)">
    `POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>

  <Tab title="Japan (Tokyo)">
    `POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation`
  </Tab>
</Tabs>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ##### Request parameters <span id="en-6740266-async-req-params-h5" />

        ###### Headers <span id="en-6740266-async-headers-h6" />

        <strong>Content-Type</strong> `string` <strong>(Required)</strong>

        The content type of the request. Must be `application/json`.

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        <strong>X-DashScope-Async</strong> `string` <strong>(Required)</strong>

        Enables asynchronous processing. Must be `enable`. The endpoint in this section accepts asynchronous requests only and does not support synchronous calls.

        <Tip>
          If this request header is missing, the error "current user api does not support synchronous calls" is returned.
        </Tip>

        ###### Request body <span id="en-6740266-async-body-h6" />

        <strong>model</strong> `string` <strong>(Required)</strong>

        The model name. Available values: `qwen-image-3.0-pro`, `qwen-image-3.0`, and `qwen-image-2.1-pro`.

        <strong>input</strong> `object` <strong>(Required)</strong>

        The input parameter object, which contains the following fields:

        <Accordion title="Properties" defaultOpen>
          <strong>messages</strong> `array` <strong>(Required)</strong>

          The request content array. <strong>Only single-round conversations are supported</strong>, so the array must contain <strong>exactly one object</strong> with `role` and `content` properties.

          <Accordion title="Properties" defaultOpen>
            <strong>role</strong>`string` <strong>(Required)</strong>

            The role of the message sender. Must be set to `user`.

            <strong>content</strong>`array` <strong>(Required)</strong>

            The message content array, with different combinations depending on the use case:

            - <strong>Text-to-image (T2I)</strong>: Contains only one `{"text": "..."}` object.
            - <strong>Image-to-image (I2I)</strong>: qwen-image-2.1-pro contains 1-10 `{"image": "..."}` objects, the qwen-image-3.0 series contains 1-3, and 1 `{"text": "..."}` object.

            <Accordion title="Properties" defaultOpen>
              <strong>image</strong> `string` <strong>(Required for I2I)</strong>

              The URL or Base64 encoded data of the input image. In I2I scenarios, qwen-image-2.1-pro supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. When multiple images are provided, the order is defined by the array sequence.

              <strong>Image requirements:</strong>

              - Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
              - Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
              - Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
              - Image size: Up to 10 MB.

              <strong>Supported input formats</strong>

              1. Public URL: HTTP and HTTPS protocols are supported.
              2. Base64 encoding: Format is `data:{MIME_type};base64,{base64_data}`.

              <strong>text</strong>`string`<strong>(Required)</strong>

              The positive prompt that describes the image content, style, and composition you want to generate or edit. Both Chinese and English are supported. Recommended maximum: 4,500 tokens.

              <strong>Note</strong>: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.
            </Accordion>
          </Accordion>
        </Accordion>

        <strong>parameters</strong> `object` (Optional)

        Additional parameters to control image generation.

        <Accordion title="Properties" defaultOpen>
          <strong>prompt\_extend</strong> `boolean` (Optional)

          Whether to enable intelligent prompt rewriting. Default: `true` (recommended). When enabled, the model optimizes the positive prompt using the method specified by `prompt_extend_mode`, which significantly improves results for simple descriptions.

          <strong>prompt\_extend\_mode</strong> `string` (Optional)

          The prompt rewriting method. Default: `direct`. Options:

          - `direct`: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
          - `agent`: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing `agent` for image-to-image (I2I) will return a 400 error.

          <strong>enable\_thinking</strong> `boolean` (Optional)

          Enables thinking mode. The default is `true`. This enhances model reasoning to improve image quality, but increases generation time. It requires `prompt_extend=true`. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.

          <strong>n</strong> `integer` (Optional)

          The number of output images. Value range: 1 to 6. Default: 1.

          <strong>size</strong> `string` (Optional)

          The output image resolution in the format `width*height`, for example `"1024*1024"`. If not specified, the model automatically recommends a resolution based on the prompt.

          - <strong>Text-to-image (T2I)</strong>: Pixel area from 512\*512 to 2048\*2048. Aspect ratio: 1:8 to 8:1.
          - <strong>Image-to-image (I2I)</strong>: Pixel area from 512\*512 to 2048\*2048. Aspect ratio: 1:8 to 8:1.

          <strong>negative\_prompt</strong> `string` (Optional)

          The negative prompt that describes content you do not want to appear in the image. Only the qwen-image-3.0 series supports this parameter.

          <strong>seed</strong> `integer` (Optional)

          The random seed. Value range: `[0, 2147483647]`. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.

          <strong>watermark</strong> `boolean` (Optional)

          Whether to add a watermark. Default: `false`.
        </Accordion>
      </td>

      <td>
        <CodeGroup>
          ```bash Text-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --header 'X-DashScope-Async: enable' \
          --data '{
              "model": "qwen-image-3.0-pro",
              "input": {
                  "messages": [
                      {
                          "role": "user",
                          "content": [
                              {
                                  "text": "A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads '\''Il Messaggero'\'' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street'\''s end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere."
                              }
                          ]
                      }
                  ]
              },
              "parameters": {
                  "prompt_extend": true
              }
          }'
          ```

          ```bash Image-to-image expandable
          curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
          --header 'Content-Type: application/json' \
          --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
          --header 'X-DashScope-Async: enable' \
          --data '{
              "model": "qwen-image-3.0-pro",
              "input": {
                  "messages": [
                      {
                          "role": "user",
                          "content": [
                              {
                                  "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                              },
                              {
                                  "text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                              }
                          ]
                      }
                  ]
              },
              "parameters": {
                  "prompt_extend": true
              }
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ##### Response parameters <span id="en-6740266-async-resp1-h5" /> <span id="en-6740266-async-resp1-section" />

        <strong>output</strong> `object`

        The task acceptance information.

        <Accordion title="Properties" defaultOpen>
          <strong>task\_id</strong> `string`

          The asynchronous task ID, used to query the task status and result. Make sure to save it.

          <strong>task\_status</strong> `string`

          The task status. Usually `PENDING` when the task is submitted, indicating only that the task has been accepted, not that the image has been generated.
        </Accordion>

        <strong>request\_id</strong> `string`

        Unique request identifier for tracing and troubleshooting.

        <strong>code</strong> `string`

        Error code. Returned only for failed requests. See [Error codes](/en/model-studio/error-code).
      </td>

      <td>
        <Tabs>
          <Tab title="Successful response">
            Save the `task_id` to query the task status and result.

            ```json
            {
                "output": {
                    "task_status": "PENDING",
                    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
                },
                "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
            }
            ```
          </Tab>

          <Tab title="Error response">
            Task creation failed. See [Error codes](/en/model-studio/error-code).

            ```json
            {
                "code": "InvalidApiKey",
                "message": "Invalid API-key provided.",
                "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

#### Step 2: Poll for results using the task ID <span id="en-6740266-async-step2-title" /> <span id="en-6740266-async-step2" />

<Tabs>
  <Tab title="Singapore">
    `GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="US (Virginia)">
    `GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="China (Beijing)">
    `GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="China (Hong Kong)">
    `GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="Germany (Frankfurt)">
    `GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="Japan (Tokyo)">
    `GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>
</Tabs>

You must use the same region, workspace, and API key as when you created the task. Cross-region or cross-workspace queries are not supported.

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ##### Request parameters <span id="en-6740266-async-step2-req-h5" />

        ###### Headers <span id="en-6740266-async-step2-headers-h6" />

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        ###### URL path parameters <span id="en-6740266-async-step2-path-h6" />

        <strong>task\_id</strong> `string` <strong>(Required)</strong>

        The ID of the task.
      </td>

      <td>
        <Tabs>
          <Tab title="Query task result">
            Replace `{task_id}` with the `task_id` value returned by the previous API call. The `task_id` is valid for queries for 24 hours, Replace `{WorkspaceId}` with your actual [workspace ID](/en/model-studio/regions#h2_migrate_domain).

            ```bash
            curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
            --header "Authorization: Bearer $DASHSCOPE_API_KEY"
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        ##### Response parameters <span id="en-6740266-async-resp2-h5" /> <span id="en-6740266-async-resp2-section" />

        <strong>output</strong> `object`

        The task output information.

        <Accordion title="Properties" defaultOpen>
          <strong>task\_id</strong> `string`

          The task ID. Valid for queries for 24 hours.

          <strong>task\_status</strong> `string`

          The status of the task.

          <Accordion title="Enumeration values" defaultOpen>
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELED
            - UNKNOWN: The task does not exist or its status is unknown.
          </Accordion>

          <strong>State transitions during polling:</strong>

          - PENDING → RUNNING → SUCCEEDED or FAILED.
          - The initial query status is usually PENDING or RUNNING.
          - When the status changes to SUCCEEDED, the response contains the generated image URL.
          - If the status is FAILED, check the error message and retry the task.

          <strong>submit\_time</strong> `string`

          The time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

          <strong>scheduled\_time</strong> `string`

          The time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

          <strong>end\_time</strong> `string`

          The time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

          <strong>rewrite\_status</strong> `string`

          The prompt rewriting status. The value depends on whether rewriting was enabled in the request and the result of the rewrite.

          <strong>choices</strong> `array`

          The list of result options.

          <Accordion title="Properties" defaultOpen>
            <strong>finish\_reason</strong> `string`

            The reason why the task stopped. The value is `stop` when the task completes normally.

            <strong>message</strong> `object`

            The message returned by the model.

            <Accordion title="Properties" defaultOpen>
              <strong>role</strong>`string`

              The role of the message. Fixed as `assistant`.

              <strong>content</strong>`array`

              The message content containing the generated image information.

              <Accordion title="Properties" defaultOpen>
                <strong>image</strong> `string`

                The URL of the generated image in PNG format. <strong>The link is valid for 24 hours</strong>. Please download and save the image promptly.
              </Accordion>
            </Accordion>
          </Accordion>
        </Accordion>

        <strong>usage</strong> `object`

        The resource usage of this call. Only returned on success. These are <strong>image input and output metering fields, not token usage</strong>.

        <Accordion title="Properties" defaultOpen>
          <Tabs>
            <Tab title="qwen-image-3.0 series">
              <strong>output\_width</strong> `integer`

              The width of the final output image in pixels.

              <strong>output\_height</strong> `integer`

              The height of the final output image in pixels.

              <strong>input\_image\_count</strong> `integer`

              The number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).

              <strong>input\_image\_type</strong> `string`

              The input image billing tier. Determined by the output resolution pixel area: `qima_input_1k` if area ≤ 2,250,000, or `qima_input_2k` if area > 2,250,000.

              <strong>output\_image\_count</strong> `integer`

              The actual number of output images returned.

              <strong>output\_image\_type</strong> `string`

              The output image billing tier. Determined by the output resolution pixel area: `qima_output_1k` if area ≤ 2,250,000, or `qima_output_2k` if area > 2,250,000.
            </Tab>

            <Tab title="qwen-image-2.1-pro">
              <strong>image\_count</strong> `integer`

              The number of images generated by the model.

              <strong>width</strong> `integer`

              The width of the generated image in pixels.

              <strong>height</strong> `integer`

              The height of the generated image in pixels.
            </Tab>
          </Tabs>
        </Accordion>

        <strong>request\_id</strong> `string`

        Unique request identifier for tracing and troubleshooting.

        <strong>code</strong> `string`

        Error code. Returned only for failed requests. See [Error codes](/en/model-studio/error-code).

        <strong>message</strong> `string`

        Detailed error message. Returned only for failed requests. See [Error codes](/en/model-studio/error-code).
      </td>

      <td>
        <Tabs>
          <Tab title="Task succeeded">
            Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.

            <CodeGroup>
              ```json qwen-image-3.0 series
              {
                  "output": {
                      "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
                      "task_status": "SUCCEEDED",
                      "submit_time": "2026-08-07 15:50:14.837",
                      "scheduled_time": "2026-08-07 15:50:14.884",
                      "end_time": "2026-08-07 15:50:33.607",
                      "rewrite_status": "not_use",
                      "choices": [
                          {
                              "finish_reason": "stop",
                              "message": {
                                  "role": "assistant",
                                  "content": [
                                      {
                                          "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                                          "type": "image"
                                      }
                                  ]
                              }
                          }
                      ]
                  },
                  "usage": {
                      "output_height": 1024,
                      "output_width": 1024,
                      "input_image_count": 0,
                      "input_image_type": "qima_input_1k",
                      "output_image_count": 1,
                      "output_image_type": "qima_output_1k"
                  },
                  "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
              }
              ```

              ```json qwen-image-2.1-pro
              {
                  "output": {
                      "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
                      "task_status": "SUCCEEDED",
                      "submit_time": "2026-08-07 15:50:14.837",
                      "scheduled_time": "2026-08-07 15:50:14.884",
                      "end_time": "2026-08-07 15:50:33.607",
                      "rewrite_status": "not_use",
                      "choices": [
                          {
                              "finish_reason": "stop",
                              "message": {
                                  "role": "assistant",
                                  "content": [
                                      {
                                          "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                                          "type": "image"
                                      }
                                  ]
                              }
                          }
                      ]
                  },
                  "usage": {
                      "image_count": 1,
                      "width": 1024,
                      "height": 1024
                  },
                  "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
              }
              ```
            </CodeGroup>
          </Tab>

          <Tab title="Task failed">
            When a task fails, `task_status` is FAILED with an error code and message. See [Error codes](/en/model-studio/error-code).

            ```json
            {
                "output": {
                    "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
                    "task_status": "FAILED",
                    "code": "InternalError",
                    "message": "An internal error has occurred."
                },
                "request_id": "31f808fd-8eef-9004-xxxxx"
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

## Error codes <span id="OajFO" /> <span id="en-6740266-error-codes-conref" />

If the model call fails and returns an error message, see [Error codes](/en/model-studio/error-code) for resolution.