Qwen Image 3 — API reference

Qwen Image 3 uses the model ID alibaba/qwen-image-3/edit. Edit images from an instruction and one to three ordered references with Qwen Image 3.

1. Calling the API

Send requests to https://api.higgsfield.ai/alibaba/qwen-image-3/edit with a JSON body matching the parameters below.

Install

Install an official server-side SDK. cURL needs no package.

npm install @higgsfield/client

Setup

Keep credentials in server-side environment variables. The SDKs accept the same KEY_ID:KEY_SECRET value under their documented variable names.

export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL

Request parameters

Parameter	Type	Required	Default	Description
`seed`	`integer`	No	`—`	Optional random seed for similar, reproducible results. Minimum: 0. Maximum: 2147483647.
`prompt`	`string`	Yes	`—`	Positive prompt or editing instruction in Chinese or English. Alibaba recommends at most 4,500 tokens. Minimum length: 1.
`image_urls`	`array[string]`	Yes	`—`	One to three ordered public image URLs used as editing references.
`resolution`	`string`	No	`"1k"`	Output resolution tier. Both tiers produce PNG images. Options: 1k, 2k.
`aspect_ratio`	`string`	No	`"1:1"`	Output aspect ratio. Exact provider-recommended dimensions are selected automatically. Options: 1:1, 2:3, 3:2, 3:4, 4:3, 7:9, 9:7, 9:16, 16:9, 21:9.
`prompt_extend`	`boolean`	No	`true`	Improve the prompt before generation. Required when thinking mode is enabled.
`enable_thinking`	`boolean`	No	`true`	Use model reasoning to improve image quality. Requires prompt enhancement.
`negative_prompt`	`string`	No	`—`	Content, styles, or artifacts to avoid in the output.
`prompt_extend_mode`	`string`	No	`"direct"`	Direct enhancement is available for every request; agent enhancement is text-to-image only. Options: direct.

2. Authentication

The official SDKs read credentials from the server environment and send the required Authorization: Key KEY_ID:KEY_SECRET header.

API Key

Never expose the secret in browser-side code or commit it to source control. The TypeScript SDK is server-side only. For direct HTTP calls, use:

Authorization: Key $HF_KEY

3. Queue

subscribe submits the asynchronous request and waits for a terminal result. The TypeScript SDK polls automatically when withPolling: true; the Python SDK's synchronous subscribe call also waits. A completed request returns generated files in the images array.

Submit and wait

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": "A cinematic scene at sunset",
      "image_urls": [
        "https://example.com/input.jpg"
      ],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "prompt_extend": true,
      "enable_thinking": true,
      "prompt_extend_mode": "direct"
    },
    withPolling: true,
  },
);

console.log(result);

Explicit lifecycle control

Use the Python SDK when a worker needs explicit status, result, or cancellation control for an existing request. The TypeScript v2 client currently exposes automatic polling through subscribe.

import higgsfield_client

request_id = "{request_id}"
status = higgsfield_client.status(request_id=request_id)
result = higgsfield_client.result(request_id=request_id)
higgsfield_client.cancel(request_id=request_id)