Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Z-Image API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name z-image
Type Image generation (text-to-image)
Endpoint POST /v1/tasks
Pricing See HiAPI Pricing

Tongyi Z-Image Turbo: an efficient 6B photorealistic text-to-image model with 8-step distilled inference for near-instant generation, accurate bilingual (Chinese and English) in-image text rendering, and one of the lowest per-image prices — built for high-volume and latency-sensitive workloads.

Production guidance

Production guidance
  • For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
  • GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
  • Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

High-volume, low-cost generation

One of the lowest per-image price tiers among HiAPI image models, paired with 8-step high-throughput inference — ideal for e-commerce assets, bulk illustrations and data augmentation where cost per image matters.

callback
Photorealistic portraits and photography looks

Top-tier realism among open-source models (ranked #1 open-source on the Artificial Analysis text-to-image leaderboard, Dec 2025), with natural skin and hair detail. Spell out camera, lens and film terms in the prompt for a documentary look instead of the default retouched style.

prompt
Short Chinese and English in-image text

Accurate bilingual in-image text rendering, including small font sizes — great for poster headlines, signage, slogans and labels. Put the exact text at the very start of the prompt and keep the composition simple.

prompt
Latency-sensitive real-time apps

The Turbo distilled variant needs only 8 inference steps (sub-second upstream on H800), suiting live previews, interactive creation and in-chat image generation.

promptaspect_ratio

Request parameters

model string required

Fixed value z-image.

example z-image
input object required

Business parameters. Put Z-Image-specific configuration here.

prompt string required

Text prompt for image generation, in Chinese or English. Up to 1000 characters; staying under 800 is more reliable. Put the subject and any text to render at the very beginning for best results.

aspect_ratio enum optional

Output aspect ratio, five presets. Use 3:4 or 9:16 for vertical posters and 16:9 for wide scenes.

default 1:1 enum: 1:14:33:416:99:16
callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback
when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Photorealistic portrait (film look)

Lead with the subject, then spell out lighting, depth of field and a 35mm film look to get a documentary feel instead of the default retouched style.

Request body
{
  "model": "z-image",
  "input": {
    "prompt": "Photorealistic portrait of a young woman in a plain qipao sitting by a wooden window, soft natural light, shallow depth of field, fine realistic skin and hair texture, 35mm film look",
    "aspect_ratio": "3:4"
  }
}
Bilingual signage text rendering

State the exact text early in the prompt and keep the composition simple — fewer scene elements means more accurate text.

Request body
{
  "model": "z-image",
  "input": {
    "prompt": "Close-up of a minimalist wooden cafe sign, crisp readable Chinese name and English SHIGUANG COFFEE below, warm lighting, realistic commercial photography",
    "aspect_ratio": "4:3"
  }
}
16:9 photorealistic wide scene

Use 16:9 for wide scenes; stylized settings still keep a realistic finish.

Request body
{
  "model": "z-image",
  "input": {
    "prompt": "Cyberpunk rainy night at Shanghai Bund, neon and skyscraper lights reflected on wet streets, people with umbrellas, cinematic blue-purple grade, ultra realistic",
    "aspect_ratio": "16:9"
  }
}

Getting the result

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the generated image from output[].url.
  4. When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

How is Z-Image billed?

Billed per image, in one of the lowest price tiers among HiAPI image models — well suited to high-volume generation. See the live pricing page for current rates. View live pricing

Why are there no seed or negative prompt parameters?

HiAPI serves the Turbo distilled variant of Z-Image. Its 8-step inference does not support CFG or negative prompts, so negative_prompt is unavailable and seed is not exposed. Output variety for a repeated prompt is low — to get different results, rewrite the wording (angle, lighting, composition) rather than retrying the same prompt.

Any prompt length or writing tips?

The platform limit is 1000 characters; staying under 800 is more reliable (longer prompts may be truncated upstream). Put the subject and any text to render at the very beginning. Short in-image text is most accurate — long sentences and paragraphs often break, fonts cannot be specified, and crowded scenes degrade text quality, so simplify the composition for text-heavy shots.

Can I use the generated images commercially?

The Z-Image model is open-sourced under Apache 2.0, which permits commercial use. Calling it through HiAPI is billed per image with no extra model license required. Generated content must still comply with applicable laws and platform content policies.

Next steps