---
title: "Create an image generation task"
description: "Start an asynchronous image generation task with the simplified v2 API. The response returns the new task's ID."
canonical: "https://platform.pixai.art/en/docs/api-v2/image/createImage"
last-updated: "2026-11-16"
---

# Create an image generation task

Start an asynchronous image generation task with the simplified v2 API. The response returns the new task's ID.



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.

## POST https://api.pixai.art/v2/image/create

Authentication: send your API key as `Authorization: Bearer <API key>`.

Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.yaml

### Request body (`application/json`)

- `modelVersionId` (string, required)
  The unique identifier for the model version to use for generation. Preferred replacement for the deprecated `modelId` field.

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

  Example URL: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelVersionId is `<modelVersionId>`.
  Example: `"1983308862240288769"`.
- `modelId` (string, optional, deprecated)
  The unique identifier for the model version to use for generation. Taken from the model version's URL on PixAI.

  How to find modelId:
  1. Open the model page on PixAI.
  2. Click the model version you'd like to use.
  3. Copy the last path segment of the URL — that's the modelId.

  Example URL: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelId is `<modelVersionId>`.
  Note: Please use `modelVersionId` instead. `modelId` is ambiguous: it actually expects a model **version** ID instead of a model ID.
  Example: `"1983308862240288769"`.
- `prompt` (string, required)
  The main prompt describing the content you want to generate. Up to 10,000 characters on Tsubaki.2 and Tsubaki.3, 4,096 on other models.
  Length: 1 to 10000 characters.
  Example: `"1girl, green hair, solo, standing"`.
- `negativePrompt` (string, optional)
  Text describing elements to avoid in the generated image.
  Length: 0 to 4096 characters.
  Example: `"nsfw, lowres, bad anatomy"`.
- `aspectRatio` (string, optional)
  The aspect ratio of the generated image. Defaults to `1:1` when neither `aspectRatio`/`size` nor `width`/`height` is sent. Cannot be combined with `width` and `height`.

  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](https://platform.pixai.art/en/docs/references/supported-resolutions) for the full resolution mapping per size tier.
  Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `3:5`, `5:3`, `9:16`, `16:9`, `1:3`, `3:1`.
  Example: `"1:1"`.
- `size` (string, optional)
  The output resolution tier. Defaults to `1k` when neither `aspectRatio`/`size` nor `width`/`height` is sent. Cannot be combined with `width` and `height`. 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](https://platform.pixai.art/en/docs/references/supported-resolutions) for the full mapping table.
  Allowed values: `1k`, `1.5k`.
  Example: `"1k"`.
- `width` (integer, optional)
  Exact output width in pixels, for sizes the `aspectRatio`/`size` presets do not cover (e.g. Tsubaki.3's larger outputs). Send together with `height` and without `aspectRatio` and `size`.

  The size must fall within one of the model's size ranges and be a multiple of its `step`. Read them from `GET https://api.pixai.art/v2/generation-model/{modelVersionId}/size-config` (no authentication needed): each entry of `ranges` gives `minWidth`/`maxWidth`, `minHeight`/`maxHeight` and `step`, plus ready-made `presets`. A size outside every range returns `400 IMAGE_SIZE_NOT_ALLOWED`.
  Range: 1 to 10240.
  Example: `1024`.
- `height` (integer, optional)
  Exact output height in pixels. Send together with `width`; see `width` for the allowed sizes.
  Range: 1 to 10240.
  Example: `1024`.
- `mode` (string, optional)
  The inference profile controlling generation quality and speed.
  - `lite`: Fastest, basic quality.
  - `standard`: Balanced speed and quality.
  - `pro`: Higher quality, slower.
  - `ultra`: Highest quality, slowest.

  Not every mode is offered on every model or plan; an unavailable mode returns `422 INVALID_INPUT` naming the mode.
  Note: Only available for the **Tsubaki.2** and **Tsubaki.3** model families. Rejected with `400 INVALID_ARGUMENT` on other model types.
  Allowed values: `lite`, `standard`, `pro`, `ultra`.
  Example: `"standard"`.
- `style` (object (one of the variants below), optional)
  The style to apply during image generation. Can be a named preset or a custom style string.
  Note: Only available for the **Tsubaki.2** and **Tsubaki.3** model families. Silently ignored for other model types.
  - Variant 1:
    - `style.type` (string, required)
      Allowed values: `preset`.
    - `style.key` (string, required)
      A named preset style key. Available presets:
      - `anime-watercolor-impasto` — Watercolor Glow
      - `art-crayon` — Art Crayon
      - `bold-line-soft-color` — Glint & Gloom
      - `chibi` — Chibi
      - `classic-japanese` — Classic Anime
      - `clean-flat-illustration` — Clean Flat-Illustration
      - `colored-pencil-grain` — Chromatic Pencil
      - `cool-warm-oil-contrast` — Seasonal Glow
      - `desaturated-cool` — Cool Softlight
      - `flat-anime-pastel` — Pastel Flat
      - `glossy-glass-anime` — Glassy Anime
      - `grey-blocks-lineless` — Grey Wash
      - `hard-line-monochrome-accent` — Sharp Ink
      - `high-contrast-retro-vivid` — Neon Vivid
      - `holographic` — Hyper Pop
      - `korean-style` — Polished Manhwa
      - `lineart-watercolor-airy` — Luminous Wash
      - `low-saturation-expressive-eyes` — Muted & Transparent
      - `lucid-dreamy` — Lucid Dreamy
      - `luminous-retro-impasto` — Luminous Impasto
      - `minimal-flat-color` — Minimal Flat
      - `modern-oil-glamour` — Modern Glam Anime
      - `moe-pastel` — Moe Pastel
      - `oil-watercolor-blend` — Water-Infused Oil
      - `painterly-doodle` — Tender Brushstroke
      - `paper-watercolor` — Soft Aqueous
      - `pencil-sketch` — Pencil Sketch
      - `poster-graffiti` — Neon Poster
      - `retro-comic-fusion` — Retro Fusion
      - `retro-oil-glamour` — Retro Glam Anime
      - `retro-tv-anime` — 90s Retro-Cell
      - `semi-realistic` — Semi-Real
      - `stable-vaporwave` — Neon Vaporwave
      - `tinted-sketch` — Tinted Sketch
      - `vintage-collage` — Vintage Collage
      Allowed values: `anime-watercolor-impasto`, `art-crayon`, `bold-line-soft-color`, `chibi`, `classic-japanese`, `clean-flat-illustration`, `colored-pencil-grain`, `cool-warm-oil-contrast`, `desaturated-cool`, `flat-anime-pastel`, `glossy-glass-anime`, `grey-blocks-lineless`, `hard-line-monochrome-accent`, `high-contrast-retro-vivid`, `holographic`, `korean-style`, `lineart-watercolor-airy`, `low-saturation-expressive-eyes`, `lucid-dreamy`, `luminous-retro-impasto`, `minimal-flat-color`, `modern-oil-glamour`, `moe-pastel`, `oil-watercolor-blend`, `painterly-doodle`, `paper-watercolor`, `pencil-sketch`, `poster-graffiti`, `retro-comic-fusion`, `retro-oil-glamour`, `retro-tv-anime`, `semi-realistic`, `stable-vaporwave`, `tinted-sketch`, `vintage-collage`.
  - Variant 2:
    - `style.type` (string, required)
      Allowed values: `custom`.
    - `style.custom` (string, required)
      A raw style prompt string injected as a prefix to the generation prompt. This is an advanced option — incorrect values may degrade output quality.
- `loras` (object[], optional)
  Apply one or more LoRA adapters to fine-tune output style or content. How many can be combined depends on your plan (3 without a membership, up to 15); more returns `403 LORA_NUM_EXCEEDED`.

  Use a LoRA made for the same base model as the generation model: a LoRA's page on PixAI shows its base model.

  How to find LoRA modelId:
  1. Open the LoRA model page on PixAI.
  2. Click the LoRA version you'd like to use.
  3. 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>`.
  Items: 0 to 15.
- `loras[].modelId` (string, required)
  The LoRA model version ID from the PixAI Model Market.
  Example: `"1744880666293972790"`.
- `loras[].weight` (number, optional)
  The influence weight of the LoRA adapter. Range 0.0–1.0.
  Default: `1`.
  Range: 0 to 1.
  Example: `0.7`.
- `loras[].triggerWords` (string, optional)
  Custom trigger words for this LoRA. If omitted, the LoRA's default trigger words are added automatically; an empty string adds none.
- `contextImages` (string[], optional)
  Reference images for in-context generation, e.g. keeping a character consistent or taking a pose from another image.

  Each item is a media ID: an ID from a finished task's `outputs.mediaIds`, or one returned by [Upload an image or video](https://platform.pixai.art/en/docs/api-v2/media/getImageUploadUrl). Each image must be under 4000 px on both sides.
  Note: Only available for **Tsubaki.3** (`modelVersionId` `2024383379556065549`). Other models return `400 BAD_REQUEST` ("This feature is not yet supported for this model").
  Items: 0 to 3.
  Example: `["1943547603237249965"]`.
- `seed` (integer, optional)
  Random seed for reproducible generation. Omit to use a randomly generated seed.
  Example: `42`.
- `batchSize` (integer, optional)
  Number of images to generate in one task. Supported values are `1` and `4`. Defaults to `1`.
  Allowed values: `1`, `4`.
  Default: `1`.
  Example: `4`.
- `sampling` (object, optional)
  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](https://platform.pixai.art/en/docs/references/models) page for allowed sampling methods per model.
  Note: Only available for **SDXL** and **SD v1** model families.
- `sampling.method` (string, optional)
  Sampler algorithm used during generation. Supported methods vary by model — see the [Models](https://platform.pixai.art/en/docs/references/models) page.
  Example: `"DPM++ 2M Karras"`.
- `sampling.steps` (integer, optional)
  Number of diffusion steps. Higher values can improve detail but increase generation time and cost.
  Range: 1 to 100.
  Example: `25`.
- `sampling.cfgScale` (number, optional)
  Classifier-Free Guidance (CFG) scale. Controls the balance between prompt adherence and creative freedom. Higher values follow the prompt more strictly.
  Example: `7`.
- `promptHelper` (string, optional)
  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.
  - `low` / `medium`: How freely the helper rewrites the prompt, on Tsubaki.2 and Tsubaki.3. Other models treat both as `enable`.
  Note: Enabling this field will incur additional charges.
  Allowed values: `enable`, `disable`, `low`, `medium`.
  Default: `"enable"`.
- `callbackUrl` (string, optional)
  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.
  Example: `"https://your-server.example.com/webhook"`.
- `colorPalette` (object, optional)
  Steer the colors of the image. Take a preset from `GET /v2/color-palettes/presets` and send it whole, with `"source": "preset"` added.
  Note: Only available for **Tsubaki.3** (`modelVersionId` `2024383379556065549`). Other models return `400 BAD_REQUEST` ("This feature is not yet supported for this model").
- `colorPalette.source` (string, required)
  Allowed values: `preset`, `user`.
- `colorPalette.id` (string, required)
- `colorPalette.name` (string, required)
- `colorPalette.palette` (object, required)
  Colors for the whole image and, optionally, the background and characters. `overall` or `background` is required.
- `colorPalette.palette.overall` (object, optional)
- `colorPalette.palette.overall.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.overall.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.overall.colors[].ratio` (number, required)
  Share of the image, in percent.
  Range: 0 to 100.
- `colorPalette.palette.background` (object, optional)
- `colorPalette.palette.background.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.background.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.background.colors[].ratio` (number, required)
  Share of the image, in percent.
  Range: 0 to 100.
- `colorPalette.palette.character` (object, optional)
- `colorPalette.palette.character.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.character.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.character.colors[].ratio` (number, required)
  Share of the image, in percent.
  Range: 0 to 100.
- `colorPalette.createdAt` (string, required)
- `colorPalette.updatedAt` (string, required)

Example:

```json
{
  "modelVersionId": "1983308862240288769",
  "prompt": "1girl, green hair, solo, standing",
  "aspectRatio": "9:16",
  "mode": "standard",
  "batchSize": 4,
  "seed": 12345
}
```

### Example (cURL)

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

### Responses

- `201`
  Image generation task created successfully.

  Example Response:
  ```json
  {
    "id": "1943547603237249965",
    "status": "waiting",
    "createdAt": "2025-11-07T14:54:35.000Z",
    "updatedAt": "2025-11-07T14:54:35.000Z",
    "outputs": { "mediaIds": [], "mediaUrls": [] }
  }
  ```
  Body fields:
  - `id` (string, required)
    The unique identifier for the task.
  - `status` (string, required)
    The current status of the task.
    Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`.
  - `createdAt` (string, required)
    The time the task was created.
  - `updatedAt` (string, required)
    The time the task was last updated.
  - `startedAt` (string, optional)
    The time the task started running.
  - `endAt` (string, optional)
    The time the task finished.
  - `taskKind` (string, optional)
    What the task makes: `t2i` or `i2i` for images, `inpaint` for `POST /v2/gen-task/inpaint`, `i2v-inhouse` for `POST /v2/frame-video/create`, `reference-video` for `POST /v2/reference-video/create`.
  - `paidQuota` (integer, optional)
    Credits charged for the task.
  - `taskStatusMsgI18n` (object, optional)
    Why a `failed` task failed.
  - `taskStatusMsgI18n.key` (string, optional)
    A stable message key.
  - `taskStatusMsgI18n.defaultMessage` (string, optional)
    The message in English.
  - `outputs` (object, optional)
    The outputs produced by the task.
  - `outputs.videoMediaId` (string, optional)
    For video tasks, the media ID of the video. Resolve it with `GET /v2/media/batch?ids=<videoMediaId>` and download `fileUrl`. `mediaIds` then holds only the poster image.
  - `outputs.seed` (string, optional)
    The seed used, as a decimal string.
  - `outputs.mediaIds` (string[], optional)
    Media IDs of the generated images. Use these IDs to fetch detailed information about each generated image.

    Generated images are not permanently retained — retrieve them as soon as possible.
  - `outputs.mediaUrls` ((string | null)[], optional)
    Public URLs of the generated images.

    Generated images are not permanently retained — retrieve them as soon as possible. If an image is unavailable, its entry may be `null`.
- `400`
  The request was rejected before a task was created. `code` says why:
  - `BAD_REQUEST` with `data.issues`: the body failed validation (each issue names the field in `path`), or a field is not supported by this model (`message` says which).
  - `INVALID_ARGUMENT`: a field is not allowed for this model family, e.g. `mode` on an SDXL model or `sampling` on Tsubaki. Only `mode` and `sampling` are checked: `mode` works only on Tsubaki models, `sampling` only on SDXL and SD v1. Remove whichever the model does not accept.
  - `IMAGE_SIZE_NOT_ALLOWED`: `width`/`height` fall outside the model's size ranges (`data.reason`). Pick a size from `GET /v2/generation-model/{modelVersionId}/size-config`, or send `aspectRatio`/`size` instead.
  - `INPUT_IMAGE_TOO_LARGE`: a `contextImages` entry is 4000 px or larger on a side.
- `401`
  Authentication required. Ensure a valid Bearer token is provided.
- `403`
  The account cannot run this task right now. `code` says why:
  - `INSUFFICIENT_BALANCE`: not enough credits for the task.
  - `WAITING_NUM_EXCEEDED`: too many of your tasks are still `waiting`. Wait for some to start before submitting more (see [Limits](https://platform.pixai.art/en/docs/quick-start/limits)).
  - `LORA_NUM_EXCEEDED`: more `loras` than your plan allows.
- `404`
  `NOT_FOUND`: no model version has the given `modelVersionId`. `FILE_NOT_FOUND`: a `contextImages` media ID does not exist.
- `422`
  - `NSFW_PROMPT_REJECTED`: the prompt was rejected by content moderation. Rephrase it; `data.logId` identifies the decision if you contact support.
  - `INVALID_INPUT`: a value is not available for this model or plan, e.g. a `mode` the model does not offer. `message` names the value.
- `500`
  Task creation failed due to an internal server error. Retry with exponential backoff.
