# Z-Image API

> Z-Image — fast, high-fidelity AI image generation & editing.

- **Provider**: Qwen
- **Model id**: `z-image`
- **Modality**: image
- **Price**: 0.46 credits

## Overview

Z-Image is called in two steps: create a generation task, then poll the task until the result is ready.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `z-image` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | A text description of the image you want to generate Max 1000 characters. (example: Photorealistic 3:4 fashion editorial at blue-hour dawn. A glamorous young woman crosses a rain-soaked city intersection barefoot after an all-night party,… — full value in the request example) |
| aspect_ratio | string | Yes | Aspect ratio for the generated image. Select 'auto' to match the first input image ratio (requires input image). (options: 1:1 \| 4:3 \| 3:4 \| 16:9 \| 9:16) (default: 1:1) |
| nsfw_checker | boolean | No | A configurable parameter. Defaults to true in the Playground. (true/false) (default: true) |

### Request example

```json
{
  "modelId": "z-image",
  "input": {
    "prompt": "Photorealistic 3:4 fashion editorial at blue-hour dawn. A glamorous young woman crosses a rain-soaked city intersection barefoot after an all-night party, wearing a silver sequin dress under an oversized black blazer, both heels hanging loosely from one hand. Wet hair, slightly smeared makeup, natural tired expression, captured mid-step rather than posing.\n\nLow 35mm street-level camera, strong asymmetry: she occupies the right third. A plain yellow taxi with NO logos or text sweeps across the left background in soft motion blur. Its wake lifts wet silver confetti into one curved airborne trail behind her, visually tracing her path. Zebra-crossing lines and reflections lead toward her.\n\nCold dawn blue mixes with fading amber streetlights. Smaller condensed white type upper-left: “AFTER HOURS” with generous margin. Small line below: “05:42 AM / STILL GOING”.\n\nRaw, tactile, expensive, candid fashion photography; realistic skin, wet asphalt, sequins, motion and reflections.",
    "aspect_ratio": "1:1",
    "nsfw_checker": true
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 0.46
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=z-image`

When `state` is `success`, the output is in `resultUrls`: `{ "state": "success", "resultUrls": [ ... ] }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |