Z-Image API: Pricing, API Key, Examples, and When to Use It

If you've searched for a "z-image api" or a "z-image-turbo api key," you probably already know the model is fast and cheap. What's harder to find is a straight answer on how to actually call it, what input it expects, and whether it's the right model for your job. This guide covers all three.

What Z-Image is, and what it's good at

Z-Image is Alibaba's Tongyi Z-Image, a text-to-image model whose whole design point is doing more with less. Alibaba's Tongyi-MAI team released the Turbo variant in late November 2025 as a compact, few-step model built to generate in only a handful of diffusion passes. In practice that efficiency is the reason you'd pick it.

Three things it does well:

• Photorealism. It's tuned for realistic photography-style output: people, products, scenes. If your prompt describes something that exists in the real world, Z-Image tends to render it convincingly.
• Speed. The Turbo variant is built to generate quickly, which keeps both latency and per-image cost down. For high-volume jobs, that adds up.
• Bilingual on-image text. This is the standout. Most image models smear text into gibberish. Z-Image renders readable words inside the image, and it handles both English and Chinese. If you make signage, posters, product mockups, or anything with a label, this matters.

Be honest about the flip side. Z-Image is not the model for every job:

• If you need strong instruction-following on complex, multi-step edits or compositions, GPT Image 2 is the stronger choice. Z-Image is a generator first, not an editing-and-reasoning engine.
• If you want a specific stylized look (illustration, a particular artistic render) rather than photoreal, another model may match your intent more directly.
• For text-heavy designs, always proofread the output. "Accurate text" means it's good, not that it's perfect every time. Render, then eyeball the words before you ship.

For a side-by-side on where each model lands, the best AI image generation API roundup compares the lineup. Full model details live on the Z-Image model page.

Getting an API key

You call Z-Image with a HiAPI key, the same key works across every model on the platform.

1. Sign up at hiapi.ai. New accounts currently get a small free credit to test with, see pricing for the current offer.
2. Open your dashboard and create an API key. It looks like sk-....
3. Send it as a bearer token on every request: Authorization: Bearer sk-<your-key>.

That's it, no separate key per model, no allow-listing. If a call comes back 401 permission_denied, the key is missing or wrong.

A minimal correct call

Z-Image runs on HiAPI's unified async task API. You submit a task, then poll for the result. Two details people get wrong:

1. The model id is z-image (plain). Pass it exactly like that.
2. The input is prompt plus aspect_ratio (and an optional resolution). Do not send a size or width x height field. The API rejects it with additional properties 'size' not allowed.

Submit the task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "A cozy independent coffee shop at golden hour, a wooden A-frame sign on the sidewalk reading \"FRESH COFFEE\", warm window light, shallow depth of field, photorealistic",
      "aspect_ratio": "1:1"
    }
  }'

The response gives you a task id:

{ "data": { "taskId": "task_abc123", "status": "queued" } }

Poll until it's done:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-<your-key>"

data.status moves through queued → handling → archiving → success (or fail). On success, the image is at data.output[0].url:

{
  "data": {
    "status": "success",
    "output": [{ "url": "https://.../z-image-result.png" }]
  }
}

Download that URL immediately. It's a temporary link and expires, so save the bytes or push them to your own storage right after you get them, don't hot-link it. Full request and polling reference is in the docs.

The "z-image-turbo" question

Search traffic for "z-image-turbo api" is real, so let's be clear. Turbo is the fast variant of the Z-Image family upstream. On HiAPI you don't call a separate z-image-turbo endpoint, the callable model id is z-image. If you've been trying to POST z-image-turbo and getting errors, that's why. Use z-image and you get the fast, efficient model behind it.

Pricing

Z-Image is billed pay-as-you-go, per image, and it's one of the more cost-efficient image models on the platform, which follows from its lightweight, few-step design. No subscription, you pay for what you generate.

Exact per-image numbers move, so this guide won't print one that's stale by the time you read it. Check the live pricing page for the current rate. If your priority is squeezing cost down across the whole catalog, the cheapest image generation API guide walks through the low-cost options and how to compare them.

When to use Z-Image vs alternatives

A quick way to decide:

Your job	Reach for
Photoreal images, fast and cheap, with readable EN/ZH text on the image	Z-Image
Complex edits, precise instruction-following, image-to-image reasoning	GPT Image 2
A specific non-photoreal or stylized aesthetic	A style-leaning model, compare on the model pages

In short: Z-Image is your default when you want realistic output at volume, or anything with text baked into the picture, without paying a premium. When the task is less "generate a great image" and more "follow a tricky instruction," move up to GPT Image 2.

FAQ

What is the Z-Image model id on the API? z-image (plain). Pass it as the model field in your POST /v1/tasks body.

Is there a separate z-image-turbo API or id? No. Turbo is the upstream speed variant of the model. On HiAPI the single callable id is z-image.

How do I get a z-image-turbo API key? The same way as any HiAPI key: sign up, create a key in the dashboard, and send it as Authorization: Bearer sk-<key>. The same key calls Z-Image and every other model.

Why does my request fail with "additional properties 'size' not allowed"? You sent a size (or width/height) field. Z-Image doesn't accept it. Use aspect_ratio (for example "1:1") instead, plus an optional resolution.

Can Z-Image render Chinese text inside the image? Yes. Accurate in-image text in both English and Chinese is one of its strengths. Proofread the output anyway, text rendering is strong but not flawless.

How much does Z-Image cost? Pay-as-you-go per image, and it's one of the cheaper options on the platform. See the pricing page for the current rate.

Takeaways

• Call z-image. There is no separate z-image-turbo endpoint on HiAPI.
• Send prompt and aspect_ratio. Never send size, the API rejects it.
• Pick Z-Image for photorealism, speed, and bilingual on-image text at low cost. Pick GPT Image 2 when you need instruction-following on complex edits.
• It's pay-as-you-go, check live pricing for the current number.
• Download output[0].url immediately, the link expires.

Ready to try it? Grab a key in the dashboard and send your first z-image task.