VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/Qwen Image API

Qwen Image API

Build image generation and editing into your app with Qwen Image APIs. Configure size, output count, and negative prompts, or use Qwen 3.0 for additional prompt expansion, thinking, and seed controls.

Get API keyView API docs
Abstract illustration for Qwen Image API
PlaygroundAPIPricingGuideFAQs

Qwen Image API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

7 parameters

Text prompt describing the image to generate (max 800 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Optional input image URL. When provided, the task runs in image edit mode.(Optional)

Ordered input image URLs for image editing mode. The prompt can reference them by their one-based order.(Optional)

minItems 1maxItems 3

Describe content that should not appear in the image.(Optional)

Exact output dimensions.(Optional)

Default: 1024*1024

Number of images to generate.(Optional)

Default: 1

Enhance and enrich the prompt automatically.(Optional)

Default: true

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/qwen-image-generator/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "prompt": "An isometric sustainable neighborhood with rooftop gardens, bicycle paths, and solar panels",
  "size": "1024*1024",
  "imageNum": "1",
  "promptExtend": true
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/qwen-image-generator/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["imageUrl"] // .data["imageUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

EndpointQwen Image Generator ↓
Required inputs
prompt
Output
Image·imageUrl
EndpointQwen 3.0 Image Generator ↓
Required inputs
prompt
Output
Image·imageUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Qwen Image Generator

Modes: text-to-image, image-edit

Additional inputs; requirements vary by mode

prompt imageUrl imageUrls imageNum

Media limits by mode
  • Image EditImage: jpg, jpeg, png, bmp, tiff, webp, gif; up to 10 MB per file; up to 3 files
Request controls
  • negativePrompt: see parameter rules
  • size: 16 accepted values; see parameter rules
  • promptExtend: default true

Qwen 3.0 Image Generator

Modes: text-to-image, image-edit

Additional inputs; requirements vary by mode

prompt imageUrl imageUrls imageNum

Media limits by mode
  • Image EditImage: jpg, jpeg, png, webp, bmp; up to 10 MB per file; up to 3 files
Request controls
  • negativePrompt: see parameter rules
  • size: 14 accepted values; see parameter rules
  • promptExtend: default true
  • promptExtendMode: "direct", "agent"
  • enableThinking: default true
  • seed: range 0 to 2147483647

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Qwen Image Generator

POST /api/v1/qwen-image-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text prompt describing the image to generate (max 800 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Edit the sample inputs for your own task before submitting.

Qwen Image Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/qwen-image-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"An isometric sustainable neighborhood with rooftop gardens, bicycle paths, and solar panels","size":"1024*1024","imageNum":"1","promptExtend":true}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules7 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText prompt describing the image to generate (max 800 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 1 · Maximum length: 800
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image edit mode. No additional field constraint listed.
imageUrlsstring[]NoNot specifiedOrdered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: 1 · Maximum items: 3
negativePromptstringNoNot specifiedDescribe content that should not appear in the image. Maximum length: 500
sizestringNo"1024*1024"Exact output dimensions. Values: "1024*1024", "1536*1536", "768*1152", "1024*1536", "1152*768", "1536*1024", "960*1280", "1080*1440", "1280*960", "1440*1080", "720*1280", "1080*1920", "1280*720", "1920*1080", "1344*576", "2048*872" · Default: "1024*1024"
imageNumstringNo"1"Number of images to generate. Values: "1", "2", "3", "4", "5", "6" · Default: "1"
promptExtendbooleanNotrueEnhance and enrich the prompt automatically. Default: true
Mode-specific fields & media limits
Text To Image rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 800 characters
negativePromptMaximum characters: 500
sizeValues: "1024*1024", "1536*1536", "768*1152", "1024*1536", "1152*768", "1536*1024", "960*1280", "1080*1440", "1280*960", "1440*1080", "720*1280", "1080*1920", "1280*720", "1920*1080", "1344*576", "2048*872"; Default: "1024*1024"
imageNumValues: "1", "2", "3", "4", "5", "6"; Default: "1"
promptExtendDefault: true
Image Edit rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 800 characters
imageUrlsImage input; up to 3 items
negativePromptMaximum characters: 500
sizeValues: "1024*1024", "1536*1536", "768*1152", "1024*1536", "1152*768", "1536*1024", "960*1280", "1080*1440", "1280*960", "1440*1080", "720*1280", "1080*1920", "1280*720", "1920*1080", "1344*576", "2048*872"
imageNumValues: "1", "2", "3", "4", "5", "6"; Default: "1"

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/qwen-image-generator/query

Use the same Bearer API key. On completion, read the imageUrl result field.

Task states and recovery ↗
Qwen Image Generator query
curl -X POST "https://vidmage.ai/api/v1/qwen-image-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Qwen 3.0 Image Generator

POST /api/v1/qwen-3-0-image-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text prompt describing the image to generate (max 3000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names.

Edit the sample inputs for your own task before submitting.

Qwen 3.0 Image Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/qwen-3-0-image-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A bilingual design-festival poster with precise Chinese and English typography, bold geometric composition, and premium print texture","imageNum":"1","promptExtend":true,"promptExtendMode":"direct","enableThinking":true}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules10 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText prompt describing the image to generate (max 3000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum length: 1 · Maximum length: 3000
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image edit mode. No additional field constraint listed.
imageUrlsstring[]NoNot specifiedOrdered input image URLs for image editing mode. The prompt can reference them by their one-based order. Minimum items: 1 · Maximum items: 3
negativePromptstringNoNot specifiedDescribe content that should not appear in the image. Maximum length: 600
sizestringNoNot specifiedExact output dimensions; leave unset to let Qwen choose automatically. Values: "1024*1024", "1600*1600", "768*1152", "1280*1920", "1152*768", "1920*1280", "768*1024", "1536*2048", "1024*768", "1792*1344", "576*1024", "1152*2048", "1024*576", "2048*1152"
imageNumstringNo"1"Number of images to generate. Values: "1", "2", "3", "4", "5", "6" · Default: "1"
promptExtendbooleanNotrueRewrite and enrich the prompt automatically. Default: true
promptExtendModestringNo"direct"Choose direct prompt rewriting or agent-based planning. Values: "direct", "agent" · Default: "direct"
enableThinkingbooleanNotrueUse deeper reasoning during prompt expansion. Default: true
seednumberNoNot specifiedRandom seed; leave unset for a random result. Minimum: 0 · Maximum: 2147483647 · Multiple of: 1 · Whole numbers only
Mode-specific fields & media limits
Text To Image rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 3000 characters
negativePromptMaximum characters: 600
sizeValues: "1024*1024", "1600*1600", "768*1152", "1280*1920", "1152*768", "1920*1280", "768*1024", "1536*2048", "1024*768", "1792*1344", "576*1024", "1152*2048", "1024*576", "2048*1152"
imageNumValues: "1", "2", "3", "4", "5", "6"; Default: "1"
promptExtendDefault: true
promptExtendModeValues: "direct", "agent"; Default: "direct"
enableThinkingDefault: true
seedRange: 0 to 2147483647
Image Edit rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 3000 characters
imageUrlsImage input; up to 3 items
negativePromptMaximum characters: 600
sizeValues: "1024*1024", "1600*1600", "768*1152", "1280*1920", "1152*768", "1920*1280", "768*1024", "1536*2048", "1024*768", "1792*1344", "576*1024", "1152*2048", "1024*576", "2048*1152"
imageNumValues: "1", "2", "3", "4", "5", "6"; Default: "1"
promptExtendDefault: true
promptExtendModeValues: "direct", "agent"; Default: "direct"
enableThinkingDefault: true
seedRange: 0 to 2147483647

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/qwen-3-0-image-generator/query

Use the same Bearer API key. On completion, read the imageUrl result field.

Task states and recovery ↗
Qwen 3.0 Image Generator query
curl -X POST "https://vidmage.ai/api/v1/qwen-3-0-image-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Qwen Image Generatorimage API1 image request: 5 creditsimageNum: 1
How this is calculated
  • Base rate: 5 credits / generation

Base charge is per generation at the selected resolution.

imageNum multiplies the base charge by the selected output count.

Estimate your own request ↗
5 credits / generationSee calculation details
Qwen 3.0 Image Generatorimage API1 image request: 10 creditsimageNum: 1
How this is calculated
  • Base rate: 10 credits / generation

Base charge is per generation at the selected resolution.

imageNum multiplies the base charge by the selected output count.

Each reference image adds 1 credit.

Estimate your own request ↗
10 credits / generationSee calculation details
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About Qwen Image API

VidMage's Qwen Image API is an image generation and editing interface with standard Qwen Image and Qwen Image 3.0 capabilities. Both support size presets, requested output counts, negative prompts, and up to three editing references. Qwen Image 3.0 adds prompt expansion, thinking, and seed controls, with settings specific to each mode. To explore this model's browser workflow, open VidMage's Qwen Image Generator.

Qwen Image API capabilities

Generate with canvas presets
Choose a listed size and requested image count, then describe the scene and any exclusions.
Edit with source references
Supply up to three reference images and explain the changes your application should request from them.
Configure Qwen 3.0 prompt handling
Use its direct or agent expansion mode, thinking switch, and seed as separate request controls.

What you can build

Ad concept selection

Give a marketing team several visual answers to the same campaign brief. A supported canvas and requested image count define the draft set; a selection board helps the team choose a composition before headlines and ad testing enter the process.

Product scene revisions

Keep the product reference in view while trying a different setting. Supply the source images, explain the background change, and list unwanted details in the negative prompt. Comparing the result with the original supports the seller's choice of listing image.

Fictional setting design

Story locations need a visual identity: a crowded market, a sparse room, or a forest path after rain. Qwen 3.0's prompt controls offer ways to explore those descriptions, with selected images grouped by location for the illustration team.

How to use Qwen Image API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read imageUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Choose sizes from the right capability
Both routes use size strings such as 1024*1024, but their complete preset lists differ. imageNum is a separate string from "1" through "6" for requested outputs.
Validate the editing path
Both edit modes allow up to three sources; Qwen 3.0 requires a minimum 384 pixel short edge. The generic route's edit mode does not list promptExtend.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/qwen-image-generator/query
Completed result
imageUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • Midjourney Image API↗
  • Grok Image API↗
  • Seedream API↗
  • Wan Image API↗
  • Nano Banana API↗
  • Z-Image API↗
  • GPT Image API↗
  • AI Image to Image API for Prompted Edits↗