--- title: "Z-Image JSON Prompt Guide — 1-Credit Image API" description: "Beginner-friendly Z-Image JSON prompt guide: every field explained, 3 copy-paste examples, and when to use it vs alternatives. 1 credit on AI Content Drop." canonical: "https://aicontentdrop.com/blog/z-image-json-prompt-guide" source: "https://aicontentdrop.com/blog/z-image-json-prompt-guide" --- ## What This Guide Does This guide teaches you how to write a valid JSON request for **Z-Image**, Alibaba's Qwen-powered image-generation model — and the single cheapest model in the AI Content Drop marketplace at **1 credit per image**. By the end you'll be able to send your first request to the Z-Image API and understand every field in the JSON, even if you've never called an AI model API before. We'll cover what each field controls, three copy-paste prompt bodies for different creative goals, how to send the request (with both `curl` and JavaScript examples), and a plain-English cost breakdown showing exactly what you get for 1 credit. If you've already explored [prompt engineering fundamentals](https://aicontentdrop.com/blog/ai-prompt-engineering-secrets), this is where you put them to work on the most budget-friendly image model on the platform. ## What Is Z-Image? Z-Image is a **text-to-image** model built on Alibaba Cloud's **Qwen** multimodal research stack and served through the [DashScope international API](https://modelstudio.console.alibabacloud.com/). It generates still images — product renders, character portraits, illustrative scenes — from a text description you write. Unlike video models such as Veo or Kling, Z-Image produces a single frame rather than a sequence of frames. Z-Image's standout strength is **cost efficiency at adequate quality**: it produces clean, usable images fast enough and cheaply enough to justify running 20–30 variants in a single batch without worrying about your credit balance. What it cannot do is match the photorealistic texture detail of higher-tier models like FLUX.2 or Nano Banana Pro — fine fabric weaves, hair strands, and precise lighting gradients will look softer than on a premium model. On AI Content Drop, a single Z-Image generation costs **1 credit** (from `IMAGE_CREDITS.z_image = 1` in the platform's credit table). That is the lowest rate of any image model on the platform. Credits are charged post-deduction — meaning if the request fails for any reason, nothing is deducted from your balance. A free-tier account starts with 10 credits, which gives you **10 free Z-Image generations** with no subscription required. For a comparison of how Z-Image fits into the wider image model landscape, see [best AI image models for video ad angles in 2026](https://aicontentdrop.com/blog/best-ai-image-models-for-video-ad-angles-2026). ## The Complete JSON Prompt A **JSON request body** is a structured text message you send to an API (Application Programming Interface — a service that receives your request and returns a result). JSON stands for *JavaScript Object Notation*. Despite the name it's just a text format made of key-value pairs that any programming language can read. Here is a complete Z-Image request body you can copy, paste, and run right now: ``` { "model": "wanx-v2", "input": { "prompt": "A white ceramic coffee mug on a natural oak table, morning window light streaming from the left, steam curling upward, photorealistic product photography" }, "parameters": { "size": "1024*1024", "n": 1, "style": "" } } ``` **At a glance:** `model` tells the DashScope API which model to use. `input.prompt` is your creative brief. `parameters.size` sets the output resolution using a width-times-height format with an asterisk (not an "x"). `parameters.n` controls how many images are returned in one call, and `parameters.style` sets a visual style preset —`""` lets the model decide. ## Field-by-Field Breakdown ### model **Type:** string | **Required:** yes | **Value for Z-Image:** `"wanx-v2"` This field tells the DashScope API which model engine to run your prompt through. For Z-Image, the model identifier is `"wanx-v2"`. Sending the wrong string here will return an error or route your request to a completely different model. Always double-check this value — it is case-sensitive. - Good: "model": "wanx-v2" — correct identifier for Z-Image - Bad: "model": "z-image" — not a valid DashScope model string; the API will return a "model not found" error ### input.prompt **Type:** string | **Required:** yes | **Max length:** ~500 characters (confirm in the latest DashScope docs) This is your creative description — the text the model uses to understand what to paint. Z-Image responds best to concise, noun-led descriptions: subject first, then material or style, then lighting or mood. Avoid sentences structured like commands ("Generate an image of…") — just describe the scene directly ("a glass bottle on a marble surface, soft studio lighting"). - Good: "A confident Black woman entrepreneur in a modern co-working space, natural light, editorial portrait, shallow depth of field" - Bad: "generate something nice and cool looking" — too vague for the model to produce a usable result; it will make something random ### parameters.size **Type:** string (enum) | **Required:** no | **Default:** `"1024*1024"` | **Separator:** asterisk `*`, not lowercase `x` The pixel dimensions of the output image, written as width-asterisk-height. This is an important quirk of the DashScope API: many developers accidentally write `"1024x1024"` (using the letter x), which returns a validation error. The correct separator is an asterisk: `"1024*1024"`. Supported sizes include square, landscape, and portrait options — see the reference table below for the full list. - Good: "size": "1024*1024" for a square social media post, or "size": "1280*720" for a landscape thumbnail - Bad: "size": "1024x1024" — uses the letter x instead of an asterisk; the API will reject this with a validation error ### parameters.n **Type:** integer | **Required:** no | **Default:** 1 | **Allowed range:** 1 – 4 (confirm in the latest DashScope docs) The number of images to generate in a single API call. Setting `n: 4` returns four different interpretations of your prompt in one response — useful for quickly comparing composition variations. On AI Content Drop, each image counts as one credit, so `n: 4` costs 4 credits total. When you're iterating on a prompt and want to see variety without making four separate calls, batching with `n` is more efficient. - Good: "n": 4 when you're exploring prompt variations and want four different compositions to choose from in a single round trip - Bad: "n": 4 for your final production asset when you only need one polished image — you'd be spending 4 credits unnecessarily ### parameters.style **Type:** string (enum) | **Required:** no | **Default:** `""` A preset that steers the overall visual aesthetic of the output. `""` lets the model infer the best style from your prompt text. Other documented values include `""` for realistic images, `""` for Japanese animation aesthetics, and `""` for painterly outputs. The angle brackets are part of the value string — they must be included exactly as shown. - Good: "style": "" when your prompt describes a real-world product scene and you want the model to prioritize photorealism over illustration - Bad: "style": "photography" (missing angle brackets) — this may return a validation error or be silently ignored depending on the API version ## Allowed Values Reference Table Use this table as a quick lookup when building prompts. All size values use the asterisk separator. Confirm the complete list in the latest Alibaba DashScope documentation, as new sizes are occasionally added. | Field | Allowed Values | Notes | | --- | --- | --- | | model | `wanx-v2` | Required; always this value for Z-Image | | parameters.size | `1024*1024`, `720*1280`, `1280*720`, `768*1152`, `1152*768`, `512*512` | Asterisk separator required; "x" causes a 400 error | | parameters.n | 1, 2, 3, 4 | Each image = 1 credit on the platform | | parameters.style | ``, ``, ``, ``, ``, `` | Angle brackets are part of the value; confirm full list in DashScope docs | | parameters.negative_prompt | Any string | Optional; describes elements to avoid in the output — confirm support in current DashScope docs | **Aspect ratio quick reference:** `1024*1024` = 1:1 square, `1280*720` = 16:9 landscape, `720*1280` = 9:16 portrait (ideal for TikTok / Reels covers), `1152*768` ≈ 3:2 landscape, `768*1152` ≈ 2:3 portrait. ## 3 Working Copy-Paste Examples ### Example 1 — E-Commerce Product Shot ``` { "model": "wanx-v2", "input": { "prompt": "A pair of white minimalist running shoes on a polished concrete pedestal, neutral grey gradient background, soft rim lighting from above, commercial product photography, crisp detail" }, "parameters": { "size": "1024*1024", "n": 4, "style": "" } } ``` Setting `n: 4` returns four distinct interpretations of the same product scene in a single API call — at 4 credits total, that's the fastest way to compare lighting and composition before picking your hero image. The `` style preset pushes the model toward photorealistic textures rather than illustration. Expect a clean, studio-style result ready for Meta Shopping ads or a Shopify product tile. Because Z-Image targets speed and budget over maximum detail, this style of controlled product prompt with simple backgrounds plays to its strengths. ### Example 2 — Portrait / Founder Character ``` { "model": "wanx-v2", "input": { "prompt": "A confident South Asian woman in her 30s, wearing a tailored navy blazer, direct eye contact, modern office background softly out of focus, warm afternoon window light, editorial portrait" }, "parameters": { "size": "768*1152", "n": 1, "style": "" } } ``` Portrait orientation (`768*1152` ≈ 2:3) gives a natural crop for LinkedIn banners, Instagram portrait posts, or UGC ad thumbnails. A single image (`n: 1`) keeps the cost at 1 credit — useful when you're refining the prompt iteratively and only need one output per round. The soft office bokeh is described in the prompt rather than controlled by a separate field, so be explicit: "softly out of focus" works better than "bokeh" alone. Z-Image handles straightforward portrait compositions well; expect solid results for UGC-style thumbnails and social media profile images. ### Example 3 — Cinematic Scene ``` { "model": "wanx-v2", "input": { "prompt": "A rain-slicked Tokyo street at dusk, neon signs reflected in puddles, lone pedestrian with an umbrella walking away from camera, moody blue-orange color grade, cinematic wide-angle composition" }, "parameters": { "size": "1280*720", "n": 2, "style": "" } } ``` Landscape orientation (`1280*720`, 16:9) matches the cinematic widescreen format — right for YouTube thumbnails, pre-roll ad storyboard frames, or video background reference images. Two outputs (`n: 2`, 2 credits) lets you compare atmospheric interpretations without committing to just one. The `` style lets the model decide whether to lean photorealistic or painterly — for moody night scenes, this often produces a satisfyingly film-like aesthetic. Use these as visual briefs when planning a video campaign, then hand the selected frame to an image-to-video model to animate it. ## How to Send the Request An **API endpoint** is a URL address where a server listens for structured requests. When you POST a JSON body to an endpoint, the server reads your fields, runs the model, and sends back a response. For Z-Image (the `wanx-v2` model), the official endpoint from Alibaba's DashScope international API is `https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis`. Authentication uses an API key you pass in an HTTP header named `Authorization`. You get this key from the [DashScope international console](https://modelstudio.console.alibabacloud.com/). You will also need to pass the header `X-DashScope-Async: enable` to receive a task ID for polling (the model is asynchronous — explained in the next section). **Using curl** (a command-line tool available on Mac, Linux, and Windows 11 — open your terminal and paste this): ``` curl -X POST \ "https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \ -H "Authorization: Bearer YOUR_DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-DashScope-Async: enable" \ -d '{ "model": "wanx-v2", "input": { "prompt": "A white ceramic coffee mug on a natural oak table, morning window light, steam curling upward, photorealistic product photography" }, "parameters": { "size": "1024*1024", "n": 1, "style": "" } }' ``` **Using JavaScript** (`fetch` — works in any modern browser or Node.js environment): ``` const response = await fetch( "https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis", { method: "POST", headers: { "Authorization": "Bearer YOUR_DASHSCOPE_API_KEY", "Content-Type": "application/json", "X-DashScope-Async": "enable" }, body: JSON.stringify({ model: "wanx-v2", input: { prompt: "A white ceramic coffee mug on a natural oak table, morning window light, steam curling upward, photorealistic product photography" }, parameters: { size: "1024*1024", n: 1, style: "" } }) } ); const data = await response.json(); console.log(data.output.task_id); // Use this to poll for the result ``` Or skip the API key entirely. Paste your prompt directly into [AI Content Drop's chat](https://aicontentdrop.com/) or head to [/generate/images](https://aicontentdrop.com/best-ai-video-generator) and select Z-Image from the model picker. The platform handles the request, polling, and image delivery for you — no API key, no terminal, no code required. ## What the Response Looks Like The DashScope API for Z-Image is **asynchronous**. That means when you POST your JSON, the server does not immediately hand back the finished image. Instead it returns a *task ID* and a status of `"PENDING"`. You then poll a separate endpoint with that task ID until generation is complete. Here is a typical initial response: ``` { "request_id": "d8f3a1b2-9e4c-4b7a-a0f1-abcdef012345", "output": { "task_id": "a7c2e1d4-1234-5678-abcd-ef0123456789", "task_status": "PENDING" }, "usage": { "image_count": 1 } } ``` `output.task_id` is the unique identifier for your generation job. Save this value. `task_status` starts as `"PENDING"`, moves to `"RUNNING"`, and finally reaches `"SUCCEEDED"` when the image is ready. To check progress, make a GET request to `https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}` with the same Authorization header. Polling once every 3–5 seconds is reasonable — Z-Image typically completes in 10–30 seconds. A completed response looks like this: ``` { "request_id": "d8f3a1b2-9e4c-4b7a-a0f1-abcdef012345", "output": { "task_id": "a7c2e1d4-1234-5678-abcd-ef0123456789", "task_status": "SUCCEEDED", "results": [ { "url": "https://dashscope-intl-result-bucket.oss-ap-southeast-1.aliyuncs.com/your-image.png" } ] }, "usage": { "image_count": 1 } } ``` `output.results[0].url` is the direct link to your finished image hosted on Alibaba's OSS storage. Fetch this URL with a GET request to download or display the image. Note that result URLs are temporary — download the image to your own storage promptly; confirm the exact expiry window in the current DashScope documentation. ## Common Errors and Fixes - **`401 Unauthorized` — "Invalid API key"** Your `Authorization` header is missing, empty, or contains a typo. Log into the DashScope console, copy your API key fresh, and paste it again — watch for leading or trailing spaces. The header must read exactly `Authorization: Bearer YOUR_KEY` (with the word "Bearer" followed by a space). - **`400 Bad Request` — size validation error** You used a lowercase "x" instead of an asterisk in the size field (e.g., `"1024x1024"` instead of `"1024*1024"`). This is the single most common Z-Image mistake. Fix: replace the "x" with `*`. - **`400 Bad Request` — "prompt is required"** The `input.prompt` key is missing or nested at the wrong level. JSON is case-sensitive and structure-sensitive. `prompt` must sit inside the `input` object, not at the top level of the request body. - **`task_status: "FAILED"` — content policy rejection** Your prompt contains words that triggered Alibaba's content filter. Remove references to violence, explicit content, or real named individuals. Rephrase abstract concepts as concrete visual descriptions — "a person looking worried" is safer than "a person in pain". - **`429 Too Many Requests` — quota exceeded** You've hit the DashScope rate limit for your account tier. Wait 60 seconds and retry. On AI Content Drop, the platform manages API quotas on your behalf — using the platform avoids this error entirely. - **style field ignored or error — missing angle brackets** The style values require angle brackets as part of the string: `""`, not `"photography"`. If you omit the brackets, the API may silently fall back to `` or return a validation error depending on the version. Always include them. - **Image URL returns 403 after some time — result expired** DashScope result URLs are time-limited. If you retrieve the task result but wait too long to fetch the image URL, it will expire. Download the image to your own storage immediately after the task status reaches `"SUCCEEDED"`. ## Z-Image vs Alternatives — When to Use This AI Content Drop gives you access to multiple image models via the [marketplace](https://aicontentdrop.com/marketplace). Here is a three-way decision table to help you pick the right model for your use case: | Scenario | Best Choice | | --- | --- | | **Use Z-Image if** you need to generate a large number of image variations quickly and cheaply — for example, 20 different product backgrounds, 30 scene thumbnails for A/B testing, or rough storyboard frames for a video campaign. At 1 credit per image, your 10 free-tier credits produce 10 complete images. On a Starter plan (150 credits/month), Z-Image gives you 150 images per month for the base subscription cost. The tradeoff is moderate detail quality — fine textures and precise lighting setups are better served by higher-tier models. For a deep dive into where Z-Image sits in the wider image model landscape, see [self-hosted vs cloud AI tradeoffs](https://aicontentdrop.com/blog/self-hosted-vs-cloud-ai). | **Z-Image** (1 credit) | | **Use FLUX.2 if** you need photorealistic product renders with fine texture detail, or if you need clean typography rendered inside the image. FLUX.2 costs 3 credits per image and significantly outperforms Z-Image on sharpness, compositional accuracy, and material rendering. The right pick for final hero images that go directly onto a landing page or into a paid ad creative. | **FLUX.2** (3 credits) | | **Use Nano Banana Pro if** you need 4K-resolution marketing hero images with exceptional skin tone rendering and lighting nuance — specifically for avatar photography used in UGC-style ads or brand spokesperson shoots. It costs 10 credits per image and trades Z-Image's price advantage for the best human-subject photorealism available on the platform. | **Nano Banana Pro** (10 credits) | ## Cost Math for Newcomers Z-Image costs **1 credit** per successful generation on AI Content Drop. Credits are only charged on success — if the request fails for any reason (content policy, API timeout, validation error), nothing is deducted from your balance. A real example: suppose you're building an initial image bank for a new product launch — 10 different background settings for a product shot, 10 different color variants, and 10 rough scene thumbnails for a campaign brief. That's **30 images × 1 credit = 30 credits**. On a free account (10 credits), you can run the first 10 for free. On the Starter plan ($19/month, 150 credits), 30 images represents just 20% of your monthly budget — leaving 120 credits for video generation or other models. Compare that to running the same 30 images on FLUX.2 (3 credits each): **30 × 3 = 90 credits**, or 60% of the Starter plan's monthly allowance. For early-stage ideation and concept exploration, Z-Image at 1 credit is the most cost-efficient path on the platform. Use Z-Image to narrow down your best concepts, then run only the finalists through a higher-quality model for production assets. On AI Content Drop's **annual unlimited tier** (Ultra and Enterprise Max annual plans), a self-hosted high-throughput image model is available at zero credit cost — ideal for studios that need hundreds of generations per week. Z-Image is the right choice when you're on a monthly plan and want to stretch every credit as far as it will go. ## Glossary **Prompt** The text description you send to the model telling it what to generate. In Z-Image, this is the `input.prompt` field inside the nested `input` object. **JSON (JavaScript Object Notation)** A plain-text format for sending structured data. It uses curly braces `{}`, key-value pairs like `"n": 1`, and commas between fields. Nested objects (like `input` and `parameters`) are written as curly-brace blocks inside the outer object. **API Request** A message you send to a server asking it to do something — in this case, generate an image. The request contains your JSON body and authentication headers. **Endpoint** The specific URL address where the API listens for requests. For Z-Image via DashScope International, this is `https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis`. **Task ID** A unique identifier the server returns immediately after you submit a generation request. Because Z-Image is asynchronous, you use this ID to poll a separate endpoint until your image is ready. **Polling** Repeatedly asking the server "is it done yet?" by making GET requests to the task status endpoint with your task ID, until `task_status` changes from `"PENDING"` to `"SUCCEEDED"`. **Aspect Ratio** The proportional relationship between the width and height of an image. A 1:1 ratio is square; 16:9 is widescreen landscape; 9:16 is portrait (the format used by TikTok, Instagram Reels, and YouTube Shorts). In Z-Image, aspect ratio is set via the `parameters.size` field. **Style Preset** A named aesthetic mode that steers the model's visual output toward a particular genre (photography, anime, watercolor, etc.). In Z-Image, style presets use angle-bracket syntax: ``. ## FAQ ### Can I just use the chat instead of writing JSON? Yes. Head to [/chat](https://aicontentdrop.com/) and describe what you want in plain English. The platform's chat system will route your message to an appropriate image model and return the generated image directly in the conversation. No JSON, no API key, no code needed. ### What if I get a 401 error? A 401 means the server rejected your API key. Your `Authorization` header is either missing, expired, or contains a copy-paste error — watch out for leading or trailing spaces around the key string. Log into your DashScope account, regenerate the key, and paste it fresh. The header must be formatted exactly as `Authorization: Bearer YOUR_KEY`. ### What if I need an aspect ratio that's not in the list? You can't request an arbitrary ratio — pick the closest supported size from the reference table and crop the image afterward in any image editor (Figma, Canva, or Photoshop all work). For example, to get a 4:3 crop, generate at `1024*1024` (1:1) and trim the top and bottom, or use `1152*768` (3:2) as the nearest landscape option and crop slightly. ### Does Z-Image support negative prompts? The DashScope API documentation describes a `negative_prompt` parameter within `parameters` for some Wanx model variants — it describes elements you want the model to avoid in the output. Support and behavior may vary by API version, so confirm availability in the latest [DashScope documentation](https://modelstudio.console.alibabacloud.com/) before relying on it. As a reliable alternative, phrase avoidance as a positive instruction in your main prompt — "clean white background, no shadows" tends to work more consistently than a negative prompt.