Qwen Image 3 — Edit images API - Higgsfield API Docs

← Qwen Image 3 Endpoint: POST https://api.higgsfield.ai/alibaba/qwen-image-3/edit Endpoint ID: alibaba/qwen-image-3/edit ▶Open API PlaygroundQwen Image 3 · Edit images↗

Usage notes

Provide 1–3 ordered reference image URLs. The list is required and cannot be empty.
enable_thinking defaults to true and requires prompt_extend=true. Set both to false to disable enhancement.
prompt_extend_mode accepts only direct; agent enhancement is unavailable on editing requests.
prompt must contain non-whitespace text. The 2k square output tier maps to 1536 by 1536 pixels.

Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

curl --request POST \
  --url https://api.higgsfield.ai/alibaba/qwen-image-3/edit \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
  "prompt": "Change the vase to matte blue while keeping the composition.",
  "image_urls": [
    "https://example.com/input-image.jpg"
  ],
  "resolution": "1k",
  "aspect_ratio": "1:1"
}'

import higgsfield_client

arguments = (
    {'prompt': 'Change the vase to matte blue while keeping the composition.',
     'image_urls': ['https://example.com/input-image.jpg'],
     'resolution': '1k',
     'aspect_ratio': '1:1'}
)
result = higgsfield_client.subscribe(
    "alibaba/qwen-image-3/edit",
    arguments=arguments,
)
print(result["images"][0]["url"])

import { config, higgsfield } from "@higgsfield/client/v2";

config({ credentials: process.env.HF_CREDENTIALS });

const result = await higgsfield.subscribe("alibaba/qwen-image-3/edit", {
  input:
    {
      "prompt": "Change the vase to matte blue while keeping the composition.",
      "image_urls": [
        "https://example.com/input-image.jpg"
      ],
      "resolution": "1k",
      "aspect_ratio": "1:1"
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.images?.[0]?.url);
}

Input schema

integer

Optional random seed for similar, reproducible results. Minimum: 0. Maximum: 2147483647.

string

required

Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens. Minimum characters: 1.

array

required

One to three ordered public image URLs used as editing references. Minimum items: 1. Maximum items: 3. Each item: string. Format: uri.

string

default:"1k"

Output resolution tier. Both tiers produce PNG images. Allowed values: "1k", "2k".

string

default:"1:1"

Output aspect ratio. Exact provider-recommended dimensions are selected automatically. Allowed values: "1:1", "2:3", "3:2", "3:4", "4:3", "7:9", "9:7", "9:16", "16:9", "21:9".

boolean

default:"true"

Improve the prompt before generation. Required when thinking mode is enabled.

boolean

default:"true"

Use model reasoning to improve image quality. Requires prompt enhancement.

string

Content, styles, or artifacts to avoid in the output.

string

default:"direct"

Direct enhancement is available for every request; agent enhancement is text-to-image only. Allowed values: "direct".

Complete JSON schema

{
  "type": "object",
  "allOf": [
    {
      "if": {
        "required": [
          "enable_thinking"
        ],
        "properties": {
          "enable_thinking": {
            "const": true
          }
        }
      },
      "then": {
        "required": [
          "prompt_extend"
        ],
        "properties": {
          "prompt_extend": {
            "const": true
          }
        }
      }
    }
  ],
  "title": "Qwen Image 3 Edit",
  "required": [
    "prompt",
    "image_urls"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "maximum": 2147483647,
      "minimum": 0,
      "description": "Optional random seed for similar, reproducible results."
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens."
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 3,
      "minItems": 1,
      "description": "One to three ordered public image URLs used as editing references."
    },
    "resolution": {
      "enum": [
        "1k",
        "2k"
      ],
      "type": "string",
      "default": "1k",
      "description": "Output resolution tier. Both tiers produce PNG images."
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "7:9",
        "9:7",
        "9:16",
        "16:9",
        "21:9"
      ],
      "type": "string",
      "default": "1:1",
      "description": "Output aspect ratio. Exact provider-recommended dimensions are selected automatically."
    },
    "prompt_extend": {
      "type": "boolean",
      "default": true,
      "description": "Improve the prompt before generation. Required when thinking mode is enabled."
    },
    "enable_thinking": {
      "type": "boolean",
      "default": true,
      "description": "Use model reasoning to improve image quality. Requires prompt enhancement."
    },
    "negative_prompt": {
      "type": "string",
      "description": "Content, styles, or artifacts to avoid in the output."
    },
    "prompt_extend_mode": {
      "enum": [
        "direct"
      ],
      "type": "string",
      "default": "direct",
      "description": "Direct enhancement is available for every request; agent enhancement is text-to-image only."
    }
  },
  "additionalProperties": false
}

Response

Submission returns a request handle. Poll status_url until status is completed, or use webhooks.

Accepted

{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}

A completed response includes the following output fields:

{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}

See idempotent requests, polling, request errors and authentication for shared request handling.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Qwen Image 3 — Edit images API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response