Z-Image Turbo API: Pricing, Documentation
by Z-Image
Z-Image Turbo is optimized for fast AI image generation without sacrificing quality, making it ideal for applications requiring quick turnaround. Through Pixazo's API, developers can generate images with reduced latency for interactive applications and high-volume workflows. The API balances speed and quality, suitable for real-time creative tools and production environments where generation time is critical.

Models Version
Get 10% Cashback on Your First Payment (up to $500)
Add funds and get 10% cashback on your first payment (up to $500).
Z-Image Turbo API Documentation
https://gateway.pixazo.ai/z-image-turbo-834/v1/z-image-turbo-request
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
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"
}
Webhook (Optional)
Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.
Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.
Webhook Headers
| Header | Required | Default | Description |
|---|---|---|---|
X-Webhook-URL | Yes (to enable) | — | HTTPS endpoint on your server that will receive the POST callback. Must respond 2xx within a few seconds (process async if needed). |
X-Webhook-Mode | No | terminal | terminal — fires once at the final status (COMPLETED/FAILED/ERROR). sync — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates. |
Example: enable webhook
X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal
Callback Payload
Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):
{
"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-xxxx-xxxx-xxxxxxxxxxxx/output.png"
],
"media_type": "image/png"
},
"created_at": "2026-05-22T13:17:32.110Z",
"updated_at": "2026-05-22 13:19:23",
"completed_at": "2026-05-22 13:19:23"
}
Failure callback shape
{
"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,
"created_at": "...",
"updated_at": "...",
"completed_at": "..."
}
Delivery semantics
- terminal mode (default) — exactly one
POSTwhen the request reaches a terminal status. No callback duringPROCESSING. - sync mode —
POSTon every status poll (with delay capped at ~15s) plus a finalPOSTat terminal status. Use when you want progress updates. - Idempotency — use
request_idas your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates. - Response — respond
200 OKwithin a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries. - HTTPS required — plain
http://URLs are rejected.
Request Parameters - Generate Request
| Parameter | Required | Type | Default | Allowed values / range | 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 | No | string or object | landscape_4_3 | square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, or a custom {width, height} object | Size and aspect ratio of the output image. Use one of the presets, or pass a custom object such as {"width": 1280, "height": 720} (each side up to 14142 px). |
| num_inference_steps | No | integer | 8 | 1–8. | Number of refinement steps the model runs while generating. Z-Image Turbo is distilled for 8 steps; lower values are faster but less detailed. |
| num_images | No | integer | 1 | 1–4. | Number of images to generate per request. Range: 1–4. |
| seed | No | integer | — | Any integer | Seed for reproducible results. The same seed with the same prompt and model version returns the same image. Omit it to get a new random image on each run. |
| enable_safety_checker | No | boolean | true | true, false | Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it. |
| enable_prompt_expansion | No | boolean | false | true, false | Automatically enriches a short prompt with extra descriptive detail before generation. Disable it when you want your prompt followed exactly. |
| output_format | No | string | png | png, jpeg, webp | Output image format. Supported values: png, jpeg, webp. |
| acceleration | No | string | regular | none, regular, high | Optimization mode that trades image quality for speed. Supported values: none, regular, high. |
| sync_mode | No | boolean | false | true, false | If true, the image is returned inline as a data URI instead of a hosted URL, and the output is not stored in the request history. |
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
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Z-Image Turbo API Pricing
Z-Image Base API Documentation
https://gateway.pixazo.ai/z-image-base/v1/z-image-base-request
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
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"
}
Webhook (Optional)
Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.
Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.
Webhook Headers
| Header | Required | Default | Description |
|---|---|---|---|
X-Webhook-URL | Yes (to enable) | — | HTTPS endpoint on your server that will receive the POST callback. Must respond 2xx within a few seconds (process async if needed). |
X-Webhook-Mode | No | terminal | terminal — fires once at the final status (COMPLETED/FAILED/ERROR). sync — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates. |
Example: enable webhook
X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal
Callback Payload
Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):
{
"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-xxxx-xxxx-xxxxxxxxxxxx/output.png"
],
"media_type": "image/png"
},
"created_at": "2026-05-22T13:17:32.110Z",
"updated_at": "2026-05-22 13:19:23",
"completed_at": "2026-05-22 13:19:23"
}
Failure callback shape
{
"request_id": "z-image-base_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ERROR",
"model_id": "z-image-base",
"error": "Description of the error",
"output": null,
"created_at": "...",
"updated_at": "...",
"completed_at": "..."
}
Delivery semantics
- terminal mode (default) — exactly one
POSTwhen the request reaches a terminal status. No callback duringPROCESSING. - sync mode —
POSTon every status poll (with delay capped at ~15s) plus a finalPOSTat terminal status. Use when you want progress updates. - Idempotency — use
request_idas your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates. - Response — respond
200 OKwithin a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries. - HTTPS required — plain
http://URLs are rejected.
Request Parameters - Z-Image base generate request
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| prompt | Yes | string | — | — | Text description describing the desired image. Be specific for best results. |
| image_size | No | string | object | landscape_4_3 | square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, or a custom {"width": w, "height": h} object (1–14142 px each) | Size / aspect ratio of the generated image. Use one of the preset values, or pass a custom object with explicit width and height in pixels. |
| num_inference_steps | No | integer | 28 | 1–50 | Number of refinement steps the model runs while generating. Higher values refine detail and quality but increase processing time; lower values are faster. |
| guidance_scale | No | number | 4 | 1–20. | Controls how closely the output follows your prompt (prompt adherence). Higher values stick more strictly to the prompt; lower values allow more creative variation. |
| seed | No | integer | — | Any integer | Seed for reproducible output. The same seed with the same prompt and settings returns the same image; omit for a random result each run. |
| num_images | No | integer | 1 | 1–4. | Number of images to generate per request. Range: 1–4. |
| enable_safety_checker | No | boolean | true | true, false | Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it. |
| output_format | No | string | png | png, jpeg, webp | Output image format. Supported values: png, jpeg, webp. |
| acceleration | No | string | regular | none, regular, high | Speed / quality trade-off. none is slowest with the highest fidelity, regular is the balanced default, and high is fastest. |
| sync_mode | No | boolean | false | true, false | If true, the image is returned inline as a data URI instead of a hosted URL, and the output is not stored in the request history. |
| negative_prompt | No | string | "" (empty) | — | Text describing what to avoid in the image (for example: blurry, extra fingers, watermark). Leave empty to apply no negative guidance. |
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 |
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
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Z-Image Base API Pricing
⚡ Performance
Live usage measured on Pixazo's gateway, split by model version. Generation time is how long a generation takes end-to-end (lower is better). Success rate is the percent of generations that complete (higher is better).
〰 Uptime
Percent of generations that succeeded over the selected period, per model version.