Your First API Call

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": "1983308862240288769",
    "prompt": "1girl, green hair, masterpiece, best quality, solo, standing, flower",
    "aspectRatio": "9:16",
    "mode": "standard"
  }'

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.

curl https://api.pixai.art/v1/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.

Poll no more frequently than once every 1.5 seconds. Use exponential backoff on retries. Each account allows up to 10 concurrent tasks in waiting or running state. See Limits for details.

Download the Image

curl -L "MEDIA_URL" -o output.png
# or via media ID:
curl -L https://api.pixai.art/v1/media/MEDIA_ID/image \
  -H "Authorization: Bearer $PIXAI_API_KEY" -o output.png

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

Next Steps

Models — browse available models
Webhook — receive task updates without polling