Qwen Image 3.0 Pro Text-to-Image API

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

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

Qwen Image 3.0 Pro Text-to-Image API turns a 1–5,000-character prompt into an asynchronous PNG or JPEG image task. Choose one of eight aspect ratios and 1K or 2K resolution; the base rate is 6.4 credits at 1K and 12 credits at 2K.

Get API Key

Input

Prompt

788/5000

Size

Resolution

Output format

Output

Ready

Continue with

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

Examples

Create a rigorous wide museum-science cutaway of one mountain glacier progressing continuously from a snowy accumulation basin on the left, through visibly compressed blue-ice layers and downhill flow in the center, to a sharply fractured calving face above water on the right. Use accurate geological strata, moraine textures, crevasses, translucent ice depth, and several clean unlabeled directional arrows embedded in the ice. Add one purely visual magnified inset of interlocking ice crystals with no border caption. Ice-blue and mineral-grey palette, fine 1K detail, generous whitespace, strong spatial clarity. The image must contain no writing or typography: no title, letters, numbers, scales, legends, captions, labels, logos, sponsors, products, promotional text, or watermarks.

Create a detailed architectural cutaway titled exactly "MOUNTAIN OBSERVATORY / 山地观测站". Show one compact observatory embedded in a rocky alpine ridge with five clearly numbered zones labeled exactly "01 DOME / 穹顶", "02 CONTROL / 控制室", "03 LAB / 实验室", "04 ARCHIVE / 档案室", and "05 SERVICE / 设备层". Include believable structural layers, stairs, cable routes, ventilation shafts, a north arrow, scale bar, and a tiny night-sky orientation diagram. Precise axonometric drawing combined with realistic concrete, timber, metal, and rock textures; disciplined Swiss grid; readable bilingual labels; no people. Educational architecture study only; no firm logo, no property marketing, no brand, no watermark, no extra text.

Create a cinematic vertical underwater scene in realistic documentary photography style, explicitly not an infographic, poster, atlas, diagram, or page layout. Near the bright ocean surface, show one small tethered buoy. A single continuous fiber-optic cable descends through open blue water to one pressure-resistant observatory station resting on a dark layered seabed. Integrate a hydrophone, camera, sediment sampler, and compact sensor housings naturally into the station, with believable construction, precise cable routing, suspended particles, subtle current streaks, and three scientifically plausible deep-sea organisms for scale. Use dramatic cyan-to-navy depth lighting and restrained amber equipment accents. Fill the frame with the underwater environment; use no border, empty text areas, panels, callout lines, writing, typography, letters, numbers, labels, logos, brands, promotions, or watermarks.

REST API

Quick Start

This flow submits one valid Qwen Image 3.0 Pro 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-pro/text-to-image",
  "input": {
    "prompt": "Create a rigorous wide museum-science cutaway of one mountain glacier progressing continuously from a snowy accumulation basin on the left, through visibly compressed blue-ice layers and downhill flow in the center, to a sharply fractured calving face above water on the right. Use accurate geological strata, moraine textures, crevasses, translucent ice depth, and several clean unlabeled directional arrows embedded in the ice. Add one purely visual magnified inset of interlocking ice crystals with no border caption. Ice-blue and mineral-grey palette, fine 1K detail, generous whitespace, strong spatial clarity. The image must contain no writing or typography: no title, letters, numbers, scales, legends, captions, labels, logos, sponsors, products, promotional text, or watermarks.",
    "size": "16:9",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, title, letters, numbers, scales, legends, captions, body copy, labels, logos, sponsor names, advertising copy, products, decorative fake data, watermark",
    "seed": 32001,
    "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-pro/text-to-image",
  "input": {
    "prompt": "Create a rigorous wide museum-science cutaway of one mountain glacier progressing continuously from a snowy accumulation basin on the left, through visibly compressed blue-ice layers and downhill flow in the center, to a sharply fractured calving face above water on the right. Use accurate geological strata, moraine textures, crevasses, translucent ice depth, and several clean unlabeled directional arrows embedded in the ice. Add one purely visual magnified inset of interlocking ice crystals with no border caption. Ice-blue and mineral-grey palette, fine 1K detail, generous whitespace, strong spatial clarity. The image must contain no writing or typography: no title, letters, numbers, scales, legends, captions, labels, logos, sponsors, products, promotional text, or watermarks.",
    "size": "16:9",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, title, letters, numbers, scales, legends, captions, body copy, labels, logos, sponsor names, advertising copy, products, decorative fake data, watermark",
    "seed": 32001,
    "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; the Pro base rate changes with 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	6.4 credits (1K) or 12 credits (2K)	1 credit = $0.005; the backend remains authoritative for final billing.

Qwen Image 3.0 Pro Text-to-Image API documentation

Qwen Image 3.0 Pro Text-to-Image

Qwen Image 3.0 Pro Text-to-Image API accepts the Pro model ID with the same prompt, aspect-ratio, format, negative-prompt, seed, and safety controls documented on this page. Unlike Standard, its base rate changes from 6.4 credits at 1K to 12 credits at 2K.

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

Coordinate complex layouts.Direct several visual elements while keeping the intended hierarchy clear.
Make text part of the design.Define visible copy, placement, and emphasis as part of the composition.
Describe observable production details.Specify surfaces, materials, lighting, and edge treatment in the prompt.
Use negative prompts and seed controls.Exclude named objects or visual traits with negative_prompt and submit an integer seed when the request needs a recorded value.

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

Write the content hierarchy.List the primary message, supporting information, focal subject, and required text.
Define the visual system.Describe composition, typography, palette, materials, lighting, and camera treatment.
Match the production target.Choose the aspect ratio and resolution for the final placement and downstream crop.
Inspect the critical details.Review text, alignment, edges, materials, and hierarchy before refining the prompt.

Pricing

Pro Text-to-Image pricing follows the requested resolution. Credits convert at $0.005 each.

Usage	Rate	Details
1K generation	6.4 credits	$0.032 per generation at the current credit conversion.
2K generation	12 credits	$0.060 per generation at the current credit conversion.

Best Use Cases

Commercial key-visual briefsDescribe the product, message, environment, and art direction in one prompt.
Typography-rich postersBuild hierarchy around a headline, supporting copy, and intentional placement.
Detailed product-scene promptsDescribe packaging, surface finish, lighting, and presentation with concrete terms.
Complex campaign layoutsOrganize several subjects and supporting elements for a high-information asset.

Pro Tips

Write visible text exactly and label each line as headline, subtitle, label, or caption.
Describe layout relationships before decorative style so hierarchy remains the priority.
Use material names, lighting direction, and edge qualities instead of broad quality adjectives.
Select 2K when the delivery genuinely benefits from the higher-resolution Pro output.
Keep seed empty during art-direction exploration and set it only for repeatable input.

Notes

Qwen Image 3.0 Pro Text-to-Image API does not accept source-image URLs.
The Playground sends prompt extension and safety checking as enabled values.
The Pro base rate changes with the selected resolution.
Generation is asynchronous; finished and failed both end the polling lifecycle.

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 Pro Text-to-Image

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

Qwen Image 3.0 Pro Text-to-Image API accepts a prompt under the qwen-image-3.0-pro/text-to-image model ID and returns an asynchronous PNG or JPEG image task. It supports eight aspect ratios, 1K/2K resolution, negative_prompt, prompt_extend, seed, and safety checking.

How do I call Pro Text-to-Image?

Submit the Pro model ID and input object with a Bearer API key, then poll the returned task ID or provide a top-level callback URL.

How much does Pro Text-to-Image cost?

A 1K generation costs 6.4 credits and a 2K generation costs 12 credits. Dollar equivalents appear in the pricing table.

What can I configure?

The prompt is required. Aspect ratio, resolution, output format, prompt expansion, negative prompt, seed, and safety checking are optional.

How do I receive the result?

Continue polling during not_started or running, then read data.files[].file_url on finished. Stop and surface error_message on failed.

Should I use Standard or Pro?

Standard costs 4.8 credits at either 1K or 2K. Pro costs 6.4 credits at 1K and 12 credits at 2K. Both modes expose the prompt and output controls listed on their pages; choose the model ID and rate required by your integration.