Qwen Image 2.1 Text To Image API Documentation

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 at 1K, 1.5K, or 2K resolution.

  • Flexible aspect ratios
    Adjust the output composition to fit different creative and publishing workflows.

  • Multiple output formats
    Export generated images as jpeg, png, or webp.

  • Native transparency Generate images with a real alpha channel. Ask for transparency in the prompt and export as png or webp.

  • Seed control
    Use a fixed seed for more reproducible generations, or -1 for a random seed.


Parameters

ParameterRequiredDescription
promptYesText prompt describing the image to generate.
aspect_ratioNoOptional output aspect ratio.
resolutionNoOutput resolution: 1k, 1.5k, or 2k. Default: 1k.
output_formatNoOutput image format: jpeg, png, or webp. Use png or webp to preserve transparency; jpeg fills transparent areas with white.
seedNoOptional random seed for generation. Use -1 for a random seed.

How to Use

  1. Write a prompt — Describe the subject, composition, environment, lighting, mood, and visual style.
  2. Choose aspect ratio optional — Set the output composition for your target use case.
  3. Choose resolution — Select 1k, 1.5k, or 2k.
  4. Choose output format optional — Select jpeg, png, or webp.
  5. Set seed optional — Use a fixed seed for reproducible results, or -1 for random generation.
  6. 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.

  1. 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.
  2. Set output_format to png or webp. 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.

ResolutionCost 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.5K or 2K when 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 1K for lower-cost iteration before moving to higher resolutions.
  • Use 2K when final output detail is more important than generation cost.
  • Choose png when you want to avoid lossy compression or need a transparent background.
  • Set a fixed seed when comparing prompt changes or generation settings.

Notes

  • prompt is required.
  • resolution defaults to 1k.
  • Supported resolutions are 1k, 1.5k, and 2k.
  • Supported output formats are jpeg, png, and webp.
  • png and webp preserve transparency; jpeg fills transparent areas with white.
  • seed=-1 selects a random seed.

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
done

Retry temporary errors only while polling, never the submit request. Errors, retries and timeouts

Parameters

Task Submission Parameters

Request Parameters

ParameterTypeRequiredDefaultRangeDescription
promptstringYes-The positive prompt for the generation.
aspect_ratiostringNo1:11: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:9The aspect ratio of the generated image. Defaults to 1:1.
resolutionstringNo1k1k, 1.5k, 2kTotal output resolution tier: 1k (~1 megapixel), 1.5k (~2.25 megapixels), or 2k (~4 megapixels).
output_formatstringNojpegjpeg, png, webpThe format of the output image.
seedintegerNo--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

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
data.idstringUnique identifier for the prediction, Task Id
data.modelstringModel ID used for the prediction
data.outputsarrayOutput values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed)
data.urlsobjectObject containing related API endpoints
data.statusstringTask status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses.
data.created_atstringISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds

Result Request Parameters

ParameterTypeRequiredDefaultDescription
idstringYes-Task ID

Result Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
dataobjectThe prediction data object containing all details
data.idstringUnique identifier for the prediction
data.modelstringModel ID used for the prediction
data.outputsarray<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.urlsobjectObject containing related API endpoints
data.statusstringStatus: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses
data.created_atstringISO timestamp of when the request was created
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds
© 2026 WaveSpeedAI. All rights reserved.