# Z-Image API

> Provider: **Z-Image**
> Source: https://www.pixazo.ai/models/z-image

Fast image generation.

## Z-Image Turbo

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/z-image-turbo-834/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Generate Request - Z-Image Turbo API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/z-image-turbo-834/v1/z-image-turbo-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A hyper-realistic close-up of an Omo Valley tribal elder, adorned with white chalk patterns and a headdress of dried flowers, seed pods, and bottle caps. Razor-sharp skin texture with every pore and wrinkle visible. A warm firelight glows in the elder's soulful eyes against a blurred, smoky hut interior, captured in a Leica M6 / Kodak Portra 400 film aesthetic.",
  "image_size": "landscape_4_3",
  "num_inference_steps": 8,
  "num_images": 1,
  "enable_safety_checker": true,
  "output_format": "png",
  "acceleration": "none"
}
```

```
import requests
import json

url = "https://gateway.pixazo.ai/z-image-turbo-834/v1/z-image-turbo-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A hyper-realistic close-up of an Omo Valley tribal elder, adorned with white chalk patterns and a headdress of dried flowers, seed pods, and bottle caps. Razor-sharp skin texture with every pore and wrinkle visible. A warm firelight glows in the elder's soulful eyes against a blurred, smoky hut interior, captured in a Leica M6 / Kodak Portra 400 film aesthetic.",
    "image_size": "landscape_4_3",
    "num_inference_steps": 8,
    "num_images": 1,
    "enable_safety_checker": True,
    "output_format": "png",
    "acceleration": "none"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/z-image-turbo-834/v1/z-image-turbo-request';

const data = {
  prompt: "A hyper-realistic close-up of an Omo Valley tribal elder, adorned with white chalk patterns and a headdress of dried flowers, seed pods, and bottle caps. Razor-sharp skin texture with every pore and wrinkle visible. A warm firelight glows in the elder's soulful eyes against a blurred, smoky hut interior, captured in a Leica M6 / Kodak Portra 400 film aesthetic.",
  image_size: "landscape_4_3",
  num_inference_steps: 8,
  num_images: 1,
  enable_safety_checker: true,
  output_format: "png",
  acceleration: "none"
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/z-image-turbo-834/v1/z-image-turbo-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A hyper-realistic close-up of an Omo Valley tribal elder, adorned with white chalk patterns and a headdress of dried flowers, seed pods, and bottle caps. Razor-sharp skin texture with every pore and wrinkle visible. A warm firelight glows in the elder''s soulful eyes against a blurred, smoky hut interior, captured in a Leica M6 / Kodak Portra 400 film aesthetic.",
    "image_size": "landscape_4_3",
    "num_inference_steps": 8,
    "num_images": 1,
    "enable_safety_checker": true,
    "output_format": "png",
    "acceleration": "none"
  }'
```

## Output

```
{
  "request_id": "z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=z-image-turbo-834-api&operation=z-image-turbo-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Generate Request

Parameter

Required

Type

Description

prompt

Yes

string

A detailed textual description of the desired image. Be specific about subjects, styles, lighting, and composition for optimal results.

image\_size

Yes

string

The aspect ratio and resolution of the output image. Supported values: \`portrait\_3\_4\`, \`landscape\_4\_3\`, \`square\_1\_1\`, \`portrait\_9\_16\`, \`landscape\_16\_9\`.

num\_inference\_steps

Optional

integer

Number of denoising steps during image generation. Lower values speed up generation but may reduce quality. Valid range: 1–50.

num\_images

Optional

integer

Number of images to generate per request. Maximum allowed value is 4.

enable\_safety\_checker

Optional

boolean

Enables or disables content safety filtering. When enabled, potentially harmful or explicit content is blocked.

output\_format

Optional

string

File format of the generated image. Supported formats: \`png\`, \`jpeg\`, \`webp\`.

acceleration

Optional

string

Specifies hardware acceleration mode. Currently only \`none\` is supported.

## Example Request

```
{
  "prompt": "A hyper-realistic close-up of an Omo Valley tribal elder, adorned with white chalk patterns and a headdress of dried flowers, seed pods, and bottle caps. Razor-sharp skin texture with every pore and wrinkle visible. A warm firelight glows in the elder's soulful eyes against a blurred, smoky hut interior, captured in a Leica M6 / Kodak Portra 400 film aesthetic.",
  "image_size": "landscape_4_3",
  "num_inference_steps": 8,
  "num_images": 1,
  "enable_safety_checker": true,
  "output_format": "png",
  "acceleration": "none"
}
```

## Response

```
{
  "request_id": "z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'z-image-turbo-834' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "z-image-turbo-834",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "z-image-turbo-834_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "z-image-turbo-834",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/z-image-turbo-834_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Z-Image Base

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/z-image-base/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Z-Image base generate request - Z-Image base

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/z-image-base/v1/z-image-base-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Grandmother knitting by a window, an empty chair by her",
  "image_size": "landscape_4_3"
}
```

```
import requests

url = "https://gateway.pixazo.ai/z-image-base/v1/z-image-base-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "Grandmother knitting by a window, an empty chair by her",
    "image_size": "landscape_4_3"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/z-image-base/v1/z-image-base-request';

const data = {
  prompt: 'Grandmother knitting by a window, an empty chair by her',
  image_size: 'landscape_4_3'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/z-image-base/v1/z-image-base-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Grandmother knitting by a window, an empty chair by her",
    "image_size": "landscape_4_3"
  }'
```

## Output

```
{
  "request_id": "z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=z-image-base&operation=z-image-base-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Z-Image base generate request

Field

Type

Required

Default

Description

prompt

string

Yes

—

Text description describing the desired image. Be specific for best results.

image\_size

string

Yes

—

Aspect ratio of output image. Supported values: landscape\_4\_3, portrait\_3\_4, square\_1\_1, landscape\_16\_9, portrait\_9\_16.

num\_inference\_steps

integer

No

28

Number of denoising steps. Higher values improve quality but increase processing time. Range: 10–100.

guidance\_scale

number

No

4

Controls how closely the model follows the prompt. Higher values increase prompt adherence. Range: 1–20.

num\_images

integer

No

1

Number of images to generate per request. Range: 1–4.

enable\_safety\_checker

boolean

No

true

Enables content safety filtering to block inappropriate outputs.

output\_format

string

No

png

Output image format. Supported values: png, jpeg, webp.

acceleration

string

No

regular

Optimization mode. Supported values: regular, fast, ultra\_fast.

## Minimum Request

```
{
  "prompt": "Grandmother knitting by a window, an empty chair by her",
  "image_size": "landscape_4_3"
}
```

## Full Request (all options)

```
{
  "prompt": "Grandmother knitting by a window, an empty chair by her",
  "image_size": "landscape_4_3",
  "num_inference_steps": 28,
  "guidance_scale": 4,
  "num_images": 1,
  "enable_safety_checker": true,
  "output_format": "png",
  "acceleration": "regular"
}
```

## Response

```
{
  "request_id": "z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Z-Image base generate request.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

500

Internal Server Error

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'z-image-base' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "z-image-base",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "z-image-base",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/z-image-base_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.