Create an image generation task

Start to generate a new image using the simplified v2 API. The v2 API provides a streamlined interface with user-friendly parameters such as `aspectRatio`, `mode`, and named `style` presets, replacing the raw pixel dimensions and internal parameter names of v1.

Authorization

bearerAuth

AuthorizationBearer <token>

In all requests that require authentication

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

modelVersionId*string

The unique identifier for the model version to use for generation. Preferred replacement for the deprecated modelId field.

How to find modelVersionId:

Open the model page on PixAI.
Click the model version you'd like to use.
Copy the last path segment of the URL — that's the modelVersionId.

Example URL: https://pixai.art/model/<id>-<slug>/<modelVersionId> → modelVersionId is <modelVersionId>.

Length1 <= length

prompt*string

The main prompt describing the content you want to generate.

Length1 <= length

negativePrompt?string

Text describing elements to avoid in the generated image.

aspectRatio?string

The aspect ratio of the generated image. Defaults to 1:1.

Available ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 3:5, 5:3, 9:16, 16:9, 1:3, 3:1

All ratios are supported across all model types (SDXL, DiT, Tsubaki.2).

See Supported Resolutions for the full resolution mapping per size tier.

Default"1:1"

Value in"1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "3:5" | "5:3" | "9:16" | "16:9" | "1:3" | "3:1"

size?string

The output resolution tier. The longest edge is capped at 1536 px for 1.5k.

1k: ~1 megapixel (e.g. 1024×1024 at 1:1).
1.5k: ~2.36 megapixels (e.g. 1536×1536 at 1:1).

See Supported Resolutions for the full mapping table.

Default"1k"

Value in"1k" | "1.5k"

mode?stringFor Tsubaki.2 Only

The inference profile controlling generation quality and speed.

lite: Fastest, basic quality.
standard: Balanced speed and quality (default).
pro: Higher quality, slower.
ultra: Highest quality, slowest.

Default"standard"

Value in"lite" | "standard" | "pro" | "ultra"

style?|For Tsubaki.2 Only

The style to apply during image generation. Can be a named preset or a custom style string.

loras?array<>

Apply one or more LoRA adapters to fine-tune output style or content. Up to 5 LoRAs can be combined.

How to find LoRA modelId:

Open the LoRA model page on PixAI.
Click the LoRA version you'd like to use.
Copy the last path segment of the URL — that's the LoRA version ID.

Example URL: https://pixai.art/model/<loraModelId>/<loraVersionId> → LoRA version ID is <loraVersionId>.

Itemsitems <= 5

seed?integer

Random seed for reproducible generation. Omit to use a randomly generated seed.

sampling?For SDXL / SD v1

Advanced sampling parameters for fine-tuning the diffusion process. All fields are optional — omitting a field uses the model's default.

Refer to the Models page for allowed sampling methods per model.

promptHelper?string

Whether to use the built-in prompt helper to enhance the prompt before generation.

enable: Automatically enhance the prompt (default).
disable: Use the prompt as-is.

Default"enable"

Value in"enable" | "disable"

callbackUrl?string

A publicly accessible URL to receive task status updates via POST request (webhook).

We will send a POST request to the callback URL when the task status changes.

Formaturi

Response Body

`application/json`

curl -X POST "https://api.pixai.art/v2/image/create" \  -H "Content-Type: application/json" \  -d '{    "modelVersionId": "1983308862240288769",    "prompt": "1girl, green hair, solo, standing",    "aspectRatio": "9:16",    "mode": "standard"  }'

{
  "id": "string",
  "status": "waiting",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "startedAt": "2019-08-24T14:15:22Z",
  "endAt": "2019-08-24T14:15:22Z",
  "outputs": {
    "mediaIds": [
      "string"
    ],
    "mediaUrls": [
      "string"
    ]
  }
}

Empty

Create an image generation task

Authorization

Request Body

Response Body

201application/json

401

500

`application/json`