Qwen Image 3 uses the model ID alibaba/qwen-image-3/text-to-image. Generate PNG images from Chinese or English prompts with Alibaba Qwen Image 3.
1. Calling the API
Send requests to https://api.higgsfield.ai/alibaba/qwen-image-3/text-to-image with a JSON body matching the parameters below.
Install
Install an official server-side SDK. cURL needs no package.
npm install @higgsfield/clientSetup
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 cURLRequest 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. |
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, agent. |
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_KEY3. 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/text-to-image",
{
input: {
"prompt": "A cinematic scene at sunset",
"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)