Qwen image edit

Image edit shares the same model family as text-to-image, but uses the edit route. Supports JSON multimodal requests and file upload.

POST /v1/images/edits

Available models

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example:
	string	No	Request content type. For JSON bodies set ; for the client sets it automatically (e.g. curl with )—do not set it manually

Request body

Name	Type	Required	Description
	string	Yes	Must be or
	object	No	Native multimodal input with (one message only; fixed to ; has 1–3 items and one )
	object	No	Qwen image generation parameters ( in native , , , , ). When provided explicitly, the adapter uses them directly
	string	No	Edit instruction for the multipart format
	file | string	No	Reference image file for the multipart format; can be repeated for multiple files
	integer	No	Multipart output count. Treated as when omitted or
	boolean	No	Multipart watermark switch

input.messages.content item

Name	Type	Required	Description
	string	No	Text content: the edit instruction
	string	No	Reference image URL (HTTP/HTTPS) or a Data URL with MIME prefix. Formats: JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF. Official recommendation: width/height between 384–2048 px; each file ≤ 10 MB

parameters

Name	Type	Required	Description
	string	No	Output size in native format (e.g. )
	integer	No	Number of output images; upstream currently allows 1–6. Treated as when omitted or
	boolean	No	Whether to add a watermark
	boolean	No	Whether to enable prompt expansion
	integer	No	Random seed

Multipart file upload

Multipart requests submit these fields with : , , one or more , , .

Repeat the field for multiple files:

--form 'image=@/absolute/path/reference-1.png' \
--form 'image=@/absolute/path/reference-2.png'

Request example

Multimodal edit

curl --request POST https://octopusx.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-3.0-pro",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          { "image": "https://example.com/reference.png" },
          { "text": "Keep the person's facial features and change the clothing to an urban professional style" }
        ]
      }
    ]
  },
  "parameters": {
    "prompt_extend": true,
    "size": "1080*1080",
    "n": 1,
    "watermark": false
  }
}'

File upload

curl --request POST https://octopusx.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --form 'model=qwen-image-3.0-pro' \
  --form 'prompt=Keep facial features and change the clothing to an urban professional style' \
  --form 'image=@/absolute/path/reference.png' \
  --form 'n=1' \
  --form 'watermark=false'

Multiple references

{
  "model": "qwen-image-3.0-pro",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          { "image": "https://example.com/person.png" },
          { "image": "https://example.com/style.png" },
          { "text": "Keep the person from the first image and apply the painting style from the second" }
        ]
      }
    ]
  },
  "parameters": {
    "size": "1024*1536",
    "n": 1
  }
}

Data URL reference

{
  "image": "data:image/png;base64,iVBORw0KGgoAAA..."
}

Response example

200

{
  "created": 1788188983,
  "data": [
    {
      "url": "https://example.com/generated.png"
    }
  ],
  "metadata": {
    "output": {
      "choices": [
        {
          "finish_reason": "stop",
          "message": {
            "role": "assistant",
            "content": [
              {
                "type": "image",
                "image": "https://example.com/generated.png"
              }
            ]
          }
        }
      ]
    },
    "request_id": "example-request-id",
    "usage": {
      "input_image_count": 1,
      "input_image_type": "qima_input_1k",
      "output_image_count": 1,
      "output_image_type": "qima_output_1k",
      "output_width": 1080,
      "output_height": 1080
    }
  }
}

Response fields

Image-to-image / edit shares the same response structure as text-to-image. For field definitions of created, data (including url, revised_prompt), metadata (including output, request_id, usage), and the error object error (message, type, param, code), plus error-code meanings and troubleshooting, see Qwen image generation · Response fields.

The only difference from text-to-image: reflects the number of reference images actually sent for this request (always for text-to-image).

Notes

WARNING

The multipart path does not build full Qwen image parameters. To control , , or , use a JSON multimodal request.

Related endpoints

• Image APIs overview
• Qwen image generation
• Upload file
• Error codes