Qwen Image 2.1 Text To Image LoRA API Documentation
Playground
Try it on WaveSpeedAI!Qwen Image 2.1 Text-to-Image LoRA generates customized images from text prompts with support for up to 3 custom LoRA weights and 1K, 1.5K, or 2K output, enabling flexible character, style, and domain-specific image generation. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.
Features
Qwen Image 2.1 Text-to-Image LoRA generates images from text prompts with support for up to 3 custom LoRA weights. Choose between 1K, 1.5K, and 2K output resolutions, and use LoRAs to guide subject, style, or concept-specific generation.
Why Choose This?
-
Text-to-image generation
Create images directly from natural-language prompts. -
LoRA support
Apply up to3LoRA weights in a single request for stronger style or subject control. -
Up to 2K resolution
Generate at1K,1.5K, or2Kresolution. -
Flexible aspect ratios
Adjust the output composition to fit different creative workflows. -
Multiple output formats
Export generated images asjpeg,png, orwebp. -
Native transparency Generate images with a real alpha channel. Ask for transparency in the prompt and export as
pngorwebp. -
Seed control
Use a fixed seed for more reproducible generations, or-1for a random seed.
Parameters
| Parameter | Required | Description |
|---|---|---|
| prompt | Yes | Text prompt describing the image to generate. |
| loras | No | Up to 3 LoRA objects. Each item uses {path, scale}. |
| resolution | No | Output resolution: 1k, 1.5k, or 2k. Default: 1k. |
| aspect_ratio | No | Optional output aspect ratio. |
| output_format | No | Output image format: jpeg, png, or webp. Use png or webp to preserve transparency; jpeg fills transparent areas with white. |
| seed | No | Optional random seed for generation. Use -1 for a random seed. |
How to Use
- Write a prompt — Describe the subject, composition, environment, lighting, mood, and style.
- Add LoRAs optional — Provide up to
3LoRA files with individualscalevalues. - Choose resolution — Select
1k,1.5k, or2k. - Choose aspect ratio optional — Set the output composition for your target use case.
- Choose output format optional — Select
jpeg,png, orwebp. - Set seed optional — Use a fixed seed for reproducible results, or
-1for random generation. - Submit — Generate and retrieve the final image.
Transparent Backgrounds
This model generates transparency natively, so a cut-out subject comes back with a real alpha channel rather than a painted-in background.
- Ask for it in the prompt. Describe the image as transparent, for example:
This is an RGBA image with transparency. A cute cartoon dragon sticker. The image has alpha channel and the background is transparent. - Set
output_formattopngorwebp. Both carry the alpha channel.
jpeg cannot store transparency, so transparent areas are filled with white. Prompts that do not ask for transparency return a fully opaque image in every format.
Pricing
Pricing is based on the selected output resolution. LoRA support is included in the price of each generation.
| Resolution | Cost per Image |
|---|---|
1K (resolution=1k, the default) | $0.025 |
1.5K (resolution=1.5k) | $0.045 |
2K (resolution=2k) | $0.085 |
A request with default settings (1k) costs $0.025 per run.
Billing Rules
- Each generation is charged per image at the price for its selected
resolution. 1.5Kand2Kcost more than1K, as shown in the table above.- 10 images at
1kcost $0.25, at1.5kcost $0.45, and at2kcost $0.85. aspect_ratio,output_format, andseeddo not add separate charges
Best Use Cases
- Style-guided generation — Apply custom LoRAs for specific visual styles.
- Character or subject generation — Use LoRAs to reinforce recurring subjects or concepts.
- Creative image generation — Turn text ideas into polished visual outputs.
- Marketing visuals — Generate social, campaign, or promotional imagery.
- Concept art — Explore characters, environments, products, and scenes.
- High-resolution generation — Use
1.5Kor2Kwhen additional detail is needed.
Pro Tips
- Use clear prompts that describe subject, composition, lighting, and style.
- Start with one LoRA when testing, then combine multiple LoRAs if needed.
- Keep LoRA scales balanced to avoid overdriving the result.
- Use
1Kfor lower-cost iteration before moving to higher resolutions. - Choose
pngwhen you want to avoid lossy compression or need a transparent background. - Set a fixed
seedwhen comparing LoRA combinations or prompt changes.
Notes
promptis required.lorassupports up to3items.- Each LoRA item should use the
{path, scale}format. resolutiondefaults to1k.- Supported resolutions are
1k,1.5k, and2k. - Supported output formats are
jpeg,png, andwebp. pngandwebppreserve transparency;jpegfills transparent areas with white.seed=-1selects a random seed.
Related Models
- Qwen Image 2.1 Text-to-Image — Generate images directly from text prompts.
- Qwen Image 2.1 Text-to-Image LoRA — Generate images from text prompts with LoRA customization.
- Qwen Image 2.1 Edit — Edit existing images with text instructions.
- Qwen Image 2.1 Edit LoRA — Edit images with text instructions and LoRA customization.
Authentication
For authentication details, please refer to the Authentication Guide.
API Endpoints
Submit Task & Query Result
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
REQUEST_BODY=$(cat <<'JSON'
{
"prompt": "A cinematic ocean wave at sunrise, highly detailed",
"aspect_ratio": "1:1",
"resolution": "1k",
"output_format": "jpeg"
}
JSON
)
# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 \
-X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/qwen-image-2.1/text-to-image-lora" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
-H "Content-Type: application/json" \
-d "${REQUEST_BODY}"); then
printf 'Submit failed. %s\n' "${CHECK}" >&2
exit 1
fi
TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"
# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
# Transient errors (429, 5xx) are retried, honoring Retry-After.
HTTP_CODE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
--output "${BODY_FILE}" --write-out '%{http_code}' \
"${RESULT_URL}" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
case "${HTTP_CODE}" in
2??) ;;
000|429|5??) # dropped connection or temporary error: keep polling
printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
sleep 10; continue ;;
*) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
cat "${BODY_FILE}" >&2; exit 1 ;;
esac
RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')
case "${STATUS}" in
completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
failed|cancelled|timeout|deleted)
printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
*) sleep 2 ;;
esac
doneRetry temporary errors only while polling, never the submit request. Errors, retries and timeouts
Parameters
Task Submission Parameters
Request Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|---|---|---|---|---|
| prompt | string | Yes | - | The positive prompt for the generation. | |
| aspect_ratio | string | No | 1:1 | 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9 | The aspect ratio of the generated image. Defaults to 1:1. |
| resolution | string | No | 1k | 1k, 1.5k, 2k | Total output resolution tier: 1K (~1 megapixel), 1.5K (~2.25 megapixels), or 2K (~4 megapixels). |
| output_format | string | No | jpeg | jpeg, png, webp | The format of the output image. |
| loras | array<object> | No | 0 ~ 3 items | List of LoRAs to apply (max 3). | |
| loras[].path | string | Yes | - | - | URL or path to the LoRA weights. |
| loras[].scale | number | No | 1 | 0 ~ 4 | - |
| seed | integer | No | - | - | The random seed. -1 means random. |
Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data.id | string | Unique identifier for the prediction, Task Id |
| data.model | string | Model ID used for the prediction |
| data.outputs | array | Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed) |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Task status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses. |
| data.created_at | string | ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”) |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |
Result Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string | Yes | - | Task ID |
Result Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data | object | The prediction data object containing all details |
| data.id | string | Unique identifier for the prediction |
| data.model | string | Model ID used for the prediction |
| data.outputs | array<string | object> | Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model. |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Status: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses |
| data.created_at | string | ISO timestamp of when the request was created |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |