Qwen Image 3.0 Text-to-Image API

alibaba/qwen-image-3.0/text-to-image

Standard/Pro · 1K/2K · 8 ratios

Qwen Image 3.0 Standard Text-to-Image API turns a 1–5,000-character prompt into an asynchronous PNG or JPEG image task without source images. Choose one of eight aspect ratios and 1K or 2K resolution.

Get API Key

Input

Prompt

779/5000

Size

Resolution

Output format

Output

Ready

Continue with

Qwen Image 3.0 Standard Edit Qwen Image 3.0 Pro Generate Qwen Image 3.0 Pro Edit

Examples

Create a full-frame vertical ink-and-watercolor natural-history illustration of one scientifically plausible grey heron standing among dew-covered reeds at sunrise. The heron is the clear focal point, with anatomically accurate legs, beak, eye, layered feathers, and a calm alert pose. Surround it with realistic wetland plants, shallow reflective water, distant mist, and warm ivory dawn light. Use an elegant museum-quality observational illustration style with fine linework, subtle paper texture, generous natural breathing room, and no graphic-design elements. The image must contain no writing or typography of any kind: no title, letters, numbers, symbols, panels, article columns, captions, annotations, labels, legends, logos, products, promotional marks, or watermarks.

Create a landscape museum observation sheet titled exactly "OBJECT NOTES / 器物观察". Center one ancient bronze ritual vessel on a neutral plinth and surround it with exactly four precise study labels: "SILHOUETTE / 轮廓", "PATINA / 铜锈", "CAST MARK / 铸痕", and "HANDLE / 器耳". Include a small scale ruler and two thumbnail contour drawings. Quiet archival photography blended with pencil annotation, charcoal and oxidized green palette, realistic metal surface, balanced editorial grid, readable bilingual typography. Cultural education only; no institution logo, no brand, no sale context, no advertisement, no watermark, no extra text.

Create a wide three-panel public-education diagram titled exactly "A RAINDROP'S JOURNEY / 一滴雨的旅程". The three equal panels must be labeled exactly "CLOUD / 云", "STREAM / 溪流", and "WETLAND / 湿地". Use one continuous blue path to show a raindrop moving from a mountain cloud through a clear stream into a reed wetland. Add simple arrows, one elevation line, and a tiny legend with only the words "FLOW / 流动" and "REST / 停留". Friendly paper-cut illustration, clean geometry, readable bilingual text, calm blue and moss palette, clear sequence. Educational content only; no campaign logo, no sponsor, no product, no promotional callout, no watermark, no extra text.

REST API

Quick Start

This flow submits one valid Qwen Image 3.0 Text-to-Image request, captures its task_id, and reads image URLs after the asynchronous task ends.

Connect to the Vidgo API

Create an API key, keep it on the server, and send it as Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one image task

Send the current model ID, prompt to the unified submit endpoint. The example keeps only first-call fields.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "qwen-image-3.0/text-to-image",
  "input": {
    "prompt": "Create a full-frame vertical ink-and-watercolor natural-history illustration of one scientifically plausible grey heron standing among dew-covered reeds at sunrise. The heron is the clear focal point, with anatomically accurate legs, beak, eye, layered feathers, and a calm alert pose. Surround it with realistic wetland plants, shallow reflective water, distant mist, and warm ivory dawn light. Use an elegant museum-quality observational illustration style with fine linework, subtle paper texture, generous natural breathing room, and no graphic-design elements. The image must contain no writing or typography of any kind: no title, letters, numbers, symbols, panels, article columns, captions, annotations, labels, legends, logos, products, promotional marks, or watermarks.",
    "size": "3:4",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, title, letters, numbers, symbols, panels, article layout, body copy, tiny text, captions, annotations, labels, legends, maps, brand logos, product packaging, prices, sales language, promotional badges, watermarks",
    "seed": 31001,
    "enable_safety_checker": true
  }
}'

Wait for the image result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "not_started",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [{
      "file_url": "https://storage.vidgo.ai/generated/image.png",
      "file_type": "image"
    }],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete runnable polling example

Expand for the same payload end to end, including business-code, missing-task-ID, failed-state, unexpected-state, and network-error handling.

Complete runnable polling example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "qwen-image-3.0/text-to-image",
  "input": {
    "prompt": "Create a full-frame vertical ink-and-watercolor natural-history illustration of one scientifically plausible grey heron standing among dew-covered reeds at sunrise. The heron is the clear focal point, with anatomically accurate legs, beak, eye, layered feathers, and a calm alert pose. Surround it with realistic wetland plants, shallow reflective water, distant mist, and warm ivory dawn light. Use an elegant museum-quality observational illustration style with fine linework, subtle paper texture, generous natural breathing room, and no graphic-design elements. The image must contain no writing or typography of any kind: no title, letters, numbers, symbols, panels, article columns, captions, annotations, labels, legends, logos, products, promotional marks, or watermarks.",
    "size": "3:4",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, title, letters, numbers, symbols, panels, article layout, body copy, tiny text, captions, annotations, labels, legends, maps, brand logos, product packaging, prices, sales language, promotional badges, watermarks",
    "seed": 31001,
    "enable_safety_checker": true
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	Must contain 1–5,000 characters after trimming.
input.size	string	No	1:1	One of 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9.
input.resolution	string	No	1K	1K or 2K; Standard uses one base rate for either resolution.
input.output_format	string	No	png	png or jpeg.
input.prompt_extend	boolean	No	–	Controls automatic prompt expansion; the Playground explicitly sends true.
input.negative_prompt	string	No	–	Describes content to avoid, up to 5,000 characters.
input.seed	integer	No	–	Optional integer from 0 through 2,147,483,647, inclusive.
input.enable_safety_checker	boolean	No	–	Controls content safety checking. The Playground explicitly sends true by default.

Response Fields

The submit response identifies the task. The status response supplies image files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-image URL.
data.files[].file_type	string	Image results are identified as image.
data.files[].watermark_url	string \| null	Optional watermarked-file URL when present.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Image generation is in progress; continue polling.
finished
Successful terminal state; validate files and read image URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

Authentication401 means the key is missing or invalid. Fix authentication before resubmitting and never expose the key in browser code.
Validation400 indicates an invalid model ID, field, enum, length, or image count.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesStop after finished or failed. Treat finished without a valid image as a separate error.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Input mode	Prompt only	The prompt is the complete creative source.
Output	Image	Returns one or more image files asynchronously.
Resolution	1K · 2K	Defaults to 1K.
Aspect ratio	8 ratios	Supports 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9.
Output format	png · jpeg	Defaults to png.
Billing	4.8 credits at 1K or 2K	1 credit = $0.005; the backend remains authoritative for final billing.

Qwen Image 3.0 Text-to-Image API documentation

Qwen Image 3.0 Standard Text-to-Image

Qwen Image 3.0 Standard is the everyday generation tier in Alibaba's Qwen image family. It suits repeatable creative work such as product scenes, campaign concepts, posters, and typography-led assets when a text prompt is the complete source.

Why Choose Qwen Image 3.0 Standard Text-to-Image API?

Start with a written brief.Describe the subject, setting, visual hierarchy, and visible text in one instruction.
Design for the destination.Create square, portrait, landscape, or ultrawide assets for the intended placement.
Repeat requests with a recorded seed.Leave seed empty while testing prompts, then submit an integer from 0 to 2,147,483,647 when you need to reuse the same request value.
Choose PNG or JPEG output.Use PNG or JPEG for the returned image; PNG is the API default when output_format is omitted.

Parameters

Parameter	Requirement	Description
prompt	Required	Text instruction containing 1–5,000 characters after trimming.
size	Optional	Output aspect ratio. Default`1:13:22:34:33:416:99:1621:9`
resolution	Optional	Output resolution. Default`1K2K`
output_format	Optional	Output image encoding. Default`pngjpeg`
prompt_extend	Optional	Boolean that enables automatic prompt expansion.
negative_prompt	Optional	Content to avoid, up to 5,000 characters.
seed	Optional	Integer from 0 through 2,147,483,647, inclusive.
enable_safety_checker	Optional	Boolean that controls content safety checking.

How to Use

Set the visual hierarchy.Name the subject, focal point, supporting elements, and any text that must appear.
Describe the art direction.Add the setting, lighting, materials, color relationships, and camera viewpoint.
Choose the final canvas.Match the aspect ratio and resolution to the placement where the image will be used.
Generate and refine.Review composition and text accuracy, then revise concrete parts of the prompt when needed.

Pricing

Standard Text-to-Image has one base rate for both supported resolutions. Credits convert at $0.005 each.

Usage	Rate	Details
1K or 2K generation	4.8 credits	$0.024 per generation at the current credit conversion.

Best Use Cases

Product postersCombine a product concept, headline, supporting copy, and layout direction in one prompt.
Campaign concept framesExplore key visual directions at the aspect ratio required by the campaign.
Marketplace scenesPlace a described product in a controlled environment with purposeful lighting and props.
Typography-led artworkBuild an image around a specified title, caption, or concise message.

Pro Tips

Put exact visible text in quotation marks and state its position in the hierarchy.
Describe foreground, subject, background, and lighting separately when the scene is dense.
Choose the delivery ratio before prompting so the composition is built for the final crop.
Use the negative prompt for concrete unwanted objects or visual traits.
Leave seed empty while exploring; set an integer when you need repeatable input.

Notes

Qwen Image 3.0 Standard Text-to-Image API does not accept source-image URLs.
The Playground enables prompt extension and safety checking and sends both values explicitly.
Generation is asynchronous; continue polling only while the task is not_started or running.
Read generated URLs from data.files after finished, or from a configured terminal callback.

Related Models

GPT Image 2Compare quality tiers and flexible image generation or editing up to 4K.

Seedream 5.0 LiteUse 2K or 3K presets, custom sizes, and a larger multi-reference workflow.

FLUX.2Choose Pro or Flex generation and editing with multi-reference controls.

Nano Banana 2Explore 1K, 2K, and 4K image creation with an expanded reference-image limit.

Frequently Asked Questions about Qwen Image 3.0 Text-to-Image

What is the Qwen Image 3.0 Text-to-Image API?

Qwen Image 3.0 Text-to-Image is Alibaba's Standard model for creating new images from text. You describe the subject, composition, style, and visible copy, and it returns a PNG or JPEG image suited to everyday posters, product visuals, campaign concepts, and typography-led assets.

How do I call Qwen Image 3.0 Text-to-Image?

Submit the model ID and input object with a Bearer API key, then use the returned task ID to check status or configure a callback.

How much does Standard Text-to-Image cost?

A generation costs 4.8 credits at either 1K or 2K. The pricing section shows the current dollar conversion.

What inputs can I control?

Provide a prompt and optionally set aspect ratio, resolution, format, prompt expansion, negative prompt, seed, and safety checking. Exact values are listed above.

Where is the generated image returned?

A finished status response places each image URL in data.files[].file_url. A failed task returns error_message instead.

Which Qwen Image 3.0 API mode should I choose?

Use Text-to-Image when the request has no source images and Edit when it includes one to three ordered source-image URLs. Standard generation costs 4.8 credits at 1K or 2K; Pro generation costs 6.4 credits at 1K and 12 credits at 2K.