Name: Z-Image Turbo LoRA API: Text to Image with Custom LoRA
Brand: magicapi
SKU: api-magicapi-text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image Generator with LoRA API (Tongyi-MAI Z-Image Turbo)

## Overview
Z-Image Turbo LoRA is the LoRA version of Z-Image Turbo, a 6B-parameter text-to-image model developed by Tongyi-MAI. Its developer describes Z-Image Turbo as super fast.

Send a text `prompt` and, optionally, one or more LoRA weight files as URLs in `lora_weights` with a strength for each in `lora_scales`. You set the `width` and `height` (64 to 1440 pixels), the number of inference steps, the output format and quality. The output is a list of image URLs; the example returned one image.

## Features
- **Custom LoRA weights**: load LoRAs from URLs to `.safetensors`, tar or zip files in `lora_weights`.
- **LoRA strength**: `lora_scales` sets one scale per LoRA (1.0 for each when omitted). It must have as many entries as `lora_weights`.
- **Image size**: `width` and `height` from 64 to 1440 pixels (default 1024 x 1024).
- **Inference steps**: `num_inference_steps` from 1 to 50 (default 8).
- **Guidance**: `guidance_scale` 0 to 20; keep it at 0 (the default) for this Turbo model.
- **Output**: `png`, `jpg` (default) or `webp`, with `output_quality` 0 to 100 (default 80) for lossy formats.
- **Seed**: set `seed` to reproduce a result.

## Use Cases
1. **Branded or custom styles**: apply a style LoRA, such as the vintage color film look in the example.
2. **Consistent characters or products**: use a LoRA trained on a subject to generate it in new scenes.
3. **Illustrations and concept art**: quick text-to-image drafts with fixed sizes.
4. **Comparing LoRAs**: run the same prompt and seed with different `lora_weights` or `lora_scales`.

## Visual Examples
### Example Input
Prompt: "t3chnic4lly vibrant 1960s close-up of a woman sitting under a tree in a blue skit and white blouse, she has blonde wavy short hair and a smile with green eyes lake scene by a garden with flowers in the foreground  1960s styl;e film   She's holding her hand out there is a small smooth frog in her palm, she's making eye contact with the toad."

LoRA: one style LoRA at scale 1, loaded from `https://huggingface.co/renderartist/Technically-Color-Z-Image-Turbo/resolve/main/Technically_Color_Z_Image_Turbo_v1_renderartist_2000.safetensors`. The prompt starts with that LoRA's trigger word, `t3chnic4lly`.

Settings: 1024 x 1024, 8 inference steps, `guidance_scale` 0, `jpg` at quality 80.

### Example Output
![Z-Image Turbo LoRA output: a vintage color film style close-up of a smiling blonde woman under a tree holding a small frog in her palm](https://blog.api.market/wp-content/uploads/2026/10/z-image-turbo-lora-output-caxas2wh-api-market.jpeg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | Text prompt for image generation |
| `height` | integer | No | `1024` | 64 to 1440 | Height of the generated image in pixels |
| `width` | integer | No | `1024` | 64 to 1440 | Width of the generated image in pixels |
| `num_inference_steps` | integer | No | `8` | 1 to 50 | Number of inference steps. The model runs (num_inference_steps - 1) DiT forward passes |
| `guidance_scale` | number | No | `0` | 0 to 20 | Guidance scale. Should be 0 for Turbo models |
| `seed` | integer | No | none |  | Random seed. Set it for reproducible generation |
| `lora_weights` | array of strings (URLs) | No | none |  | LoRA weights as an array of URLs. Supports .safetensors URLs, tar files and zip files |
| `lora_scales` | array of numbers | No | none |  | Scale for each LoRA as an array of numbers. Must match the number of `lora_weights`. Defaults to 1.0 for each if not provided |
| `output_format` | string | No | `jpg` | `png`, `jpg`, `webp` | Format of the output images |
| `output_quality` | integer | No | `80` | 0 to 100 | Quality when saving the output images, from 0 to 100. 100 is best quality, 0 is lowest quality. Not used for png outputs |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.059 per API unit.
- **1 API unit = 1 request with up to 34 seconds of processing time.** A request that takes longer uses one unit per started 34-second block (for example, 69 seconds of processing is 3 units, $0.177).
- **Example cost**: the request below took 6.05 seconds of processing, so it used 1 API unit = **$0.059**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "29c866f1269ef45b736fbcdff00d6da2a555ecf5f4e575c93ab38c2a2f2693a1",
    "input": {
      "width": 1024,
      "height": 1024,
      "prompt": "t3chnic4lly vibrant 1960s close-up of a woman sitting under a tree in a blue skit and white blouse, she has blonde wavy short hair and a smile with green eyes lake scene by a garden with flowers in the foreground  1960s styl;e film   She'\''s holding her hand out there is a small smooth frog in her palm, she'\''s making eye contact with the toad.",
      "lora_scales": [
        1
      ],
      "lora_weights": [
        "https://huggingface.co/renderartist/Technically-Color-Z-Image-Turbo/resolve/main/Technically_Color_Z_Image_Turbo_v1_renderartist_2000.safetensors"
      ],
      "output_format": "jpg",
      "guidance_scale": 0,
      "output_quality": 80,
      "num_inference_steps": 8
    }
  }'
```

Response (201 Created):
```json
{
  "id": "caxas2wh0nrp60d1c6t8kztnpw",
  "version": "29c866f1269ef45b736fbcdff00d6da2a555ecf5f4e575c93ab38c2a2f2693a1",
  "status": "starting",
  "created_at": "2026-10-22T03:43:06.157Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "caxas2wh0nrp60d1c6t8kztnpw",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/z-image-turbo-lora-output-caxas2wh-api-market.jpeg"
  ],
  "error": null,
  "created_at": "2026-10-22T03:43:06.157Z",
  "started_at": "2026-10-22T03:44:01.893Z",
  "completed_at": "2026-10-22T03:44:07.946Z"
}
```

`output` is a list of image URLs. The example returned one image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt`, a `width` above 1440 or a `lora_scales` list that does not match `lora_weights`.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.
## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "29c866f1269ef45b736fbcdff00d6da2a555ecf5f4e575c93ab38c2a2f2693a1", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "width": 1024,
  "height": 1024,
  "prompt": "t3chnic4lly vibrant 1960s close-up of a woman sitting under a tree in a blue skit and white blouse, she has blonde wavy short hair and a smile with green eyes lake scene by a garden with flowers in the foreground  1960s styl;e film   She's holding her hand out there is a small smooth frog in her palm, she's making eye contact with the toad.",
  "lora_scales": [
    1
  ],
  "lora_weights": [
    "https://huggingface.co/renderartist/Technically-Color-Z-Image-Turbo/resolve/main/Technically_Color_Z_Image_Turbo_v1_renderartist_2000.safetensors"
  ],
  "output_format": "jpg",
  "guidance_scale": 0,
  "output_quality": 80,
  "num_inference_steps": 8
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-ultra-fast-prunaai-z-image-turbo-lora"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "29c866f1269ef45b736fbcdff00d6da2a555ecf5f4e575c93ab38c2a2f2693a1", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

output = create_and_wait_for_prediction({
    "width": 1024,
    "height": 1024,
    "prompt": "t3chnic4lly vibrant 1960s close-up of a woman sitting under a tree in a blue skit and white blouse, she has blonde wavy short hair and a smile with green eyes lake scene by a garden with flowers in the foreground  1960s styl;e film   She's holding her hand out there is a small smooth frog in her palm, she's making eye contact with the toad.",
    "lora_scales": [1],
    "lora_weights": ["https://huggingface.co/renderartist/Technically-Color-Z-Image-Turbo/resolve/main/Technically_Color_Z_Image_Turbo_v1_renderartist_2000.safetensors"],
    "output_format": "jpg",
    "guidance_scale": 0,
    "output_quality": 80,
    "num_inference_steps": 8
})
print(output)
```

## FAQ
- **What LoRA files can I use?**
  - Any URL to a `.safetensors` file, or a tar or zip file containing the weights, made for Z-Image Turbo. Put the URLs in `lora_weights`.
- **How do I set the strength of each LoRA?**
  - Use `lora_scales`, one number per entry in `lora_weights`. If you leave it out, each LoRA uses 1.0.
- **Do I need a trigger word?**
  - Many LoRAs are trained with one. The example LoRA uses `t3chnic4lly` at the start of the prompt; check the LoRA's own documentation for its trigger word.
- **Should I change `guidance_scale`?**
  - No. Keep it at 0 for this Turbo model.
- **How is a request billed?**
  - $0.059 per request that takes up to 34 seconds of processing; longer requests use one unit per started 34-second block. The example took 6.05 seconds of processing, so it cost $0.059.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, check that each LoRA URL is reachable and try again.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Z-Image Turbo LoRA API: generate images from text with the 6B parameter Z-Image Turbo model and your own LoRA weights from a URL, up to 1440 x 1440.