Qwen Image 2.1 Text To Image API Documentation
Playground
Try it on WaveSpeedAI!Qwen Image 2.1 Text-to-Image generates high-quality images from text prompts with 1K, 1.5K, and 2K output resolution tiers, supporting creative visuals, product imagery, marketing assets, social content, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.
Features
Qwen Image 2.1 Text-to-Image generates high-quality images directly from text prompts with flexible aspect ratios and output resolutions up to 2K. Choose between 1K, 1.5K, and 2K depending on your quality and cost requirements.
Why Choose This?
-
Text-to-image generation
Create images directly from natural-language prompts. -
Up to 2K resolution
Generate at1K,1.5K, or2Kresolution. -
Flexible aspect ratios
Adjust the output composition to fit different creative and publishing 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. |
| aspect_ratio | No | Optional output aspect ratio. |
| resolution | No | Output resolution: 1k, 1.5k, or 2k. Default: 1k. |
| 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 visual style.
- Choose aspect ratio optional — Set the output composition for your target use case.
- Choose resolution — Select
1k,1.5k, or2k. - 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.
| Resolution | Cost per Image |
|---|---|
| 1K | $0.02 |
| 1.5K | $0.04 |
| 2K | $0.08 |
1K is the base pricing tier. 1.5K costs 2× the base price, while 2K costs 4× the base price.
aspect_ratio, output_format, and seed do not add separate charges.
Best Use Cases
- Creative image generation — Turn natural-language ideas into finished visual concepts.
- Marketing visuals — Create campaign graphics, promotional imagery, and social content.
- Concept art — Explore environments, characters, products, and visual directions.
- Product visualization — Generate styled product concepts and presentation images.
- Editorial content — Create illustrations and supporting visuals for articles or publishing workflows.
- High-resolution generation — Use
1.5Kor2Kwhen additional output detail is needed.
Pro Tips
- Describe the subject, environment, composition, lighting, and visual style clearly.
- Include camera or framing direction when composition matters.
- Use
1Kfor lower-cost iteration before moving to higher resolutions. - Use
2Kwhen final output detail is more important than generation cost. - Choose
pngwhen you want to avoid lossy compression or need a transparent background. - Set a fixed
seedwhen comparing prompt changes or generation settings.
Notes
promptis required.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" \
-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. |
| seed | integer | No | - | - | The random seed to use for the generation. -1 means a random seed will be used. |
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 |