Quick Start

Your First API Call

Submit a task, poll its status and download the image, step by step, to make your first PixAI API request.

Base URL: https://api.pixai.art/v2

Authentication: add Authorization: Bearer YOUR_API_KEY header to every request. See How can I use PixAI API? to get an API key.

Steps

Submit a Task

Send a POST /image/create. The required fields are modelVersionId and prompt.

curl -X POST https://api.pixai.art/v2/image/create \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelVersionId": "2024383379556065549",
    "prompt": "An anime girl with long green hair in a white sundress, standing in a sunflower field at golden hour and holding a straw hat, with summer clouds and a seaside town behind her, cinematic lighting, detailed background",
    "aspectRatio": "3:5"
  }'

Response:

{
  "id": "TASK_ID",
  "status": "waiting",
  "createdAt": "2026-03-04T04:32:10.635Z",
  "updatedAt": "2026-03-04T04:32:10.635Z",
  "outputs": {
    "mediaIds": [],
    "mediaUrls": []
  }
}

Note the id in the response — this is your TASK_ID, used in the next step.

Find a modelVersionId from the model version URL on PixAI: https://pixai.art/model/<id>/<modelVersionId> — the last segment is the modelVersionId. See Models for recommended options.

Poll for Status

Repeat until status reaches a terminal state. Right after the task is created, this can answer 404 for a moment; keep polling.

curl https://api.pixai.art/v2/task/TASK_ID \
  -H "Authorization: Bearer $PIXAI_API_KEY"
StatusMeaning
waitingTask is queued
runningGeneration in progress
completedFinished, outputs are ready
failedGeneration failed
cancelledTask was cancelled

When completed, outputs.mediaUrls contains the image URLs.

{
  "id": "TASK_ID",
  "status": "completed",
  "taskKind": "t2i",
  "createdAt": "2026-03-04T04:32:10.635Z",
  "updatedAt": "2026-03-04T04:32:41.902Z",
  "outputs": {
    "seed": "12345",
    "mediaIds": ["MEDIA_ID"],
    "mediaUrls": ["MEDIA_URL"]
  }
}

Poll no more frequently than once every 1.5 seconds. Use exponential backoff on retries. Each account allows up to 10 tasks in waiting state at once (running tasks are not counted). See Limits for details.

Download the Image

curl -L "MEDIA_URL" -o output.webp
# or resolve media IDs to URLs (images: the `PUBLIC` entry in `urls`; videos: `fileUrl`):
curl "https://api.pixai.art/v2/media/batch?ids=MEDIA_ID"

Generated images are not permanently retained — download them as soon as the task completes.

All steps in one script

Create, poll and save in Python, with requests installed and your key in PIXAI_API_KEY:

import os
import time

import requests

API = "https://api.pixai.art/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['PIXAI_API_KEY']}"}

resp = requests.post(
    f"{API}/image/create",
    headers=HEADERS,
    json={
        "modelVersionId": "2024383379556065549",  # Tsubaki.3
        "prompt": (
            "An anime girl with long green hair in a white sundress, standing in a sunflower field "
            "at golden hour and holding a straw hat, with summer clouds and a seaside town behind her, "
            "cinematic lighting, detailed background"
        ),
        "aspectRatio": "3:5",
    },
)
resp.raise_for_status()
task = resp.json()

while task["status"] in ("waiting", "running"):
    time.sleep(2)
    resp = requests.get(f"{API}/task/{task['id']}", headers=HEADERS)
    if resp.status_code == 404:  # A new task can answer 404 for a moment. Keep polling.
        continue
    resp.raise_for_status()
    task = resp.json()

if task["status"] != "completed":
    raise SystemExit(f"Task ended as {task['status']}: {task.get('taskStatusMsgI18n')}")

for i, url in enumerate(task["outputs"]["mediaUrls"]):
    if url:
        image = requests.get(url)
        image.raise_for_status()
        with open(f"output-{i}.webp", "wb") as f:
            f.write(image.content)

Next Steps

  • Models — browse available models
  • Webhook — receive task updates without polling
  • Examples — complete scripts for image to video, consistent characters, inpainting and LoRAs