> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Z-Image LoRA

> Text-to-image generation API with flexible size and aspect-ratio controls

## Overview

Z-Image LoRA is an asynchronous text-to-image model for generating a single image from a prompt. It supports explicit `size` input, common `aspect_ratio` presets, optional seed control, and prompt extension.

| Capability       | Value                                             |
| ---------------- | ------------------------------------------------- |
| Model ID         | `z-image-LoRA`                                    |
| Modes            | `text-to-image`                                   |
| Default mode     | `text-to-image`                                   |
| Default size     | `1024*1536`                                       |
| Size formats     | `WIDTH*HEIGHT`, `WIDTHxHEIGHT`, `WIDTHXHEIGHT`    |
| Size range       | Each side must be between `256` and `1536` pixels |
| Aspect ratios    | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
| Prompt extension | `prompt_extend`, default `true`                   |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint                                   | Purpose                               |
| ------ | ------------------------------------------ | ------------------------------------- |
| `POST` | `/generateTask/z-image-LoRA`               | Submit a text-to-image task           |
| `GET`  | `/statusTask/z-image-LoRA?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/z-image-LoRA" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "a cinematic portrait of a warrior standing in falling snow",
      "aspect_ratio": "16:9",
      "prompt_extend": true
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/z-image-LoRA?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Processing response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/image.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Generate with aspect ratio

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "a cinematic portrait of a warrior standing in falling snow",
    "aspect_ratio": "16:9",
    "prompt_extend": true
  }
}
```

### Generate with explicit size

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "a watercolor mountain lake at sunrise",
    "size": "1024*1536",
    "seed": 42,
    "prompt_extend": false
  }
}
```

## Parameters

<ParamField body="request_type" type="string" required default="async">
  Result delivery mode. Use `async` and poll with `statusTask`.
</ParamField>

<ParamField body="input" type="object" required>
  Z-Image LoRA input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" default="text-to-image">
      Generation mode. This model supports `text-to-image` only. If omitted by SDK helpers, APIXO uses `text-to-image`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Prompt text describing the image to generate. Must be a non-empty string.
    </ParamField>

    <ParamField body="size" type="string" default="1024*1536">
      Optional explicit output size. Supports `WIDTH*HEIGHT`, `WIDTHxHEIGHT`, and `WIDTHXHEIGHT`, for example `1024*1536`, `1024x1536`, or `1024X1536`. Width and height must each be between `256` and `1536`. When `size` is provided, it takes precedence over `aspect_ratio`.
    </ParamField>

    <ParamField body="aspect_ratio" type="string" default="2:3">
      Output aspect ratio used when `size` is not provided. Supported values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`.
    </ParamField>

    <ParamField body="seed" type="integer">
      Optional random seed. Use a fixed non-negative integer seed for more reproducible experiments.
    </ParamField>

    <ParamField body="prompt_extend" type="boolean" default="true">
      Whether to enable prompt extension. Prompt extension does not add an extra public charge.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/z-image-LoRA` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing generated image URLs in `resultUrls`. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds when available.
</ResponseField>

## Billing

Z-Image LoRA is billed per generated image.

| Unit                | APIXO price       |
| ------------------- | ----------------- |
| One generated image | `$0.0156 / image` |

Prompt extension does not add an extra public charge.

For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Z-Image LoRA tasks are asynchronous. Actual latency varies by prompt complexity and current queue load.

| Use case            | Recommended first poll  | Poll interval |
| ------------------- | ----------------------- | ------------- |
| Standard generation | 10s after task creation | 5s-10s        |

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/api-reference/system).

## Size rules

* If neither `size` nor `aspect_ratio` is provided, the default output size is `1024*1536`.
* `size` supports `*`, `x`, and `X` separators.
* `size` takes precedence over `aspect_ratio`.
* Explicit `size` requires width and height to each stay within `256-1536`.
* `aspect_ratio` is used only when `size` is not provided.
* Supported `aspect_ratio` values map to platform-managed output sizes within the allowed range.

| Aspect ratio | Output size |
| ------------ | ----------- |
| `1:1`        | `1536*1536` |
| `2:3`        | `1024*1536` |
| `3:2`        | `1536*1024` |
| `3:4`        | `1152*1536` |
| `4:3`        | `1536*1152` |
| `9:16`       | `864*1536`  |
| `16:9`       | `1536*864`  |

## Errors and troubleshooting

### HTTP errors

| Code  | Meaning                                              | What to do                           |
| ----- | ---------------------------------------------------- | ------------------------------------ |
| `400` | Invalid request body, mode, parameter type, or value | Fix the request before retrying      |
| `401` | Missing or invalid API key                           | Check the `Authorization` header     |
| `402` | Insufficient balance or quota                        | Add balance or switch account/key    |
| `403` | Key or route cannot access the model                 | Check permissions and route strategy |
| `404` | Task not found                                       | Verify the `taskId` and model ID     |
| `429` | Rate limit or concurrency limit reached              | Retry with exponential backoff       |
| `500` | Server or unmapped model error                       | Retry with backoff                   |
| `502` | Model service error                                  | Retry with backoff                   |
| `504` | Model service timeout                                | Retry or poll again later            |

### Request validation

| Condition                          | Backend behavior                                     |
| ---------------------------------- | ---------------------------------------------------- |
| Invalid `mode`                     | Returns a mode validation error; use `text-to-image` |
| Missing or empty `prompt`          | Returns a missing-parameter or validation error      |
| Invalid `size` format              | Returns a size format validation error               |
| `size` outside `256-1536` per side | Returns a size range validation error                |
| Unsupported `aspect_ratio`         | Returns the supported aspect-ratio list              |
| Negative `seed`                    | Returns a seed validation error                      |

See [Error Codes](/docs/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/docs/models)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Pricing](https://apixo.ai/pricing)