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"| Status | Meaning |
|---|---|
waiting | Task is queued |
running | Generation in progress |
completed | Finished, outputs are ready |
failed | Generation failed |
cancelled | Task 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)