Qwen Image 2.1 Text To Image LoRA API Documentation

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 to 3 LoRA weights in a single request for stronger style or subject control.

  • Up to 2K resolution
    Generate at 1K, 1.5K, or 2K resolution.

  • Flexible aspect ratios
    Adjust the output composition to fit different creative 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.
lorasNoUp to 3 LoRA objects. Each item uses {path, scale}.
resolutionNoOutput resolution: 1k, 1.5k, or 2k. Default: 1k.
aspect_ratioNoOptional output aspect ratio.
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 style.
  2. Add LoRAs optional — Provide up to 3 LoRA files with individual scale values.
  3. Choose resolution — Select 1k, 1.5k, or 2k.
  4. Choose aspect ratio optional — Set the output composition for your target use case.
  5. Choose output format optional — Select jpeg, png, or webp.
  6. Set seed optional — Use a fixed seed for reproducible results, or -1 for random generation.
  7. 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. LoRA support is included in the price of each generation.

ResolutionCost 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.5K and 2K cost more than 1K, as shown in the table above.
  • 10 images at 1k cost $0.25, at 1.5k cost $0.45, and at 2k cost $0.85.
  • aspect_ratio, output_format, and seed do 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.5K or 2K when 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 1K for lower-cost iteration before moving to higher resolutions.
  • Choose png when you want to avoid lossy compression or need a transparent background.
  • Set a fixed seed when comparing LoRA combinations or prompt changes.

Notes

  • prompt is required.
  • loras supports up to 3 items.
  • Each LoRA item should use the {path, scale} format.
  • 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-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
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.
lorasarray<object>No0 ~ 3 itemsList of LoRAs to apply (max 3).
loras[].pathstringYes--URL or path to the LoRA weights.
loras[].scalenumberNo10 ~ 4-
seedintegerNo--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

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.