---
title: "Your First API Call"
description: "Submit a task, poll its status and download the image, step by step, to make your first PixAI API request."
canonical: "https://platform.pixai.art/en/docs/quick-start/first-api-call"
last-updated: "2026-11-17"
---

# 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?](/en/docs/quick-start/enroll-in-api) to get an API key.

Steps [#steps]

<div className="fd-steps">
  <div className="fd-step">
    Submit a Task [#submit-a-task-step]

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

    ```bash
    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:

    ```json
    {
      "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.

    <Callout type="info">
      Find a `modelVersionId` from the model version URL on PixAI: `https://pixai.art/model/<id>/<modelVersionId>` — the last segment is the `modelVersionId`. See [Models](/en/docs/references/models#recommended-models) for recommended options.
    </Callout>
  </div>

  <div className="fd-step">
    Poll for Status [#poll-for-status-step]

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

    ```bash
    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.

    ```json
    {
      "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"]
      }
    }
    ```

    <Callout type="warn">
      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](/en/docs/quick-start/limits) for details.
    </Callout>
  </div>

  <div className="fd-step">
    Download the Image [#download-the-image-step]

    ```bash
    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"
    ```

    <Callout type="warn">
      Generated images are **not permanently retained** — download them as soon as the task completes.
    </Callout>
  </div>
</div>

All steps in one script [#all-steps-in-one-script]

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

```python
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 [#next-steps]

* [Models](/en/docs/references/models) — browse available models
* [Webhook](/en/docs/references/webhook) — receive task updates without polling
* [Examples](/en/docs/quick-start#steps) — complete scripts for image to video, consistent characters, inpainting and LoRAs
