A developer's guide to calling Alibaba's Tongyi Z-Image through the HiAPI task API, what it's good at, and when to reach for something else.

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.
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:
Be honest about the flip side. Z-Image is not the model for every job:
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.
You call Z-Image with a HiAPI key, the same key works across every model on the platform.
sk-....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.
Z-Image runs on HiAPI's unified async task API. You submit a task, then poll for the result. Two details people get wrong:
z-image (plain). Pass it exactly like that.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.
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.
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.
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.
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.
z-image. There is no separate z-image-turbo endpoint on HiAPI.prompt and aspect_ratio. Never send size, the API rejects it.output[0].url immediately, the link expires.Ready to try it? Grab a key in the dashboard and send your first z-image task.
Key Takeaways