---
title: "첫 번째 API 호출"
description: "작업 제출, 상태 폴링, 이미지 다운로드까지 PixAI API로 첫 번째 요청을 보내는 과정을 단계별로 안내합니다."
canonical: "https://platform.pixai.art/ko/docs/quick-start/first-api-call"
last-updated: "2026-11-17"
---

# 첫 번째 API 호출

작업 제출, 상태 폴링, 이미지 다운로드까지 PixAI API로 첫 번째 요청을 보내는 과정을 단계별로 안내합니다.





기본 URL: `https://api.pixai.art/v2`

인증: 모든 요청에 `Authorization: Bearer YOUR_API_KEY` 헤더를 추가하세요. API 키 발급 방법은 [PixAI API를 사용하려면?](/ko/docs/quick-start/enroll-in-api)을 참고하세요.

단계 [#단계]

<div className="fd-steps">
  <div className="fd-step">
    작업 제출 [#작업-제출-step]

    `POST /image/create`를 전송합니다. 필수 필드는 `modelVersionId`와 `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"
      }'
    ```

    응답:

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

    응답의 `id`를 기록해 두세요 — 다음 단계에서 사용하는 `TASK_ID`입니다.

    <Callout type="info">
      `modelVersionId`는 PixAI의 모델 버전 URL `https://pixai.art/model/<id>/<modelVersionId>`에서 마지막 세그먼트입니다. 추천 모델은 [모델](/ko/docs/references/models#recommended-models)을 참고하세요.
    </Callout>
  </div>

  <div className="fd-step">
    상태 폴링 [#상태-폴링-step]

    `status`가 완료 상태가 될 때까지 반복합니다. 작업을 생성한 직후에는 잠시 `404`가 반환될 수 있으니 계속 폴링하세요.

    ```bash
    curl https://api.pixai.art/v2/task/TASK_ID \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    ```

    | 상태          | 의미          |
    | :---------- | :---------- |
    | `waiting`   | 작업이 대기 중    |
    | `running`   | 생성 진행 중     |
    | `completed` | 완료, 결과물 준비됨 |
    | `failed`    | 생성 실패       |
    | `cancelled` | 작업이 취소됨     |

    `completed` 상태가 되면 `outputs.mediaUrls`에 이미지 URL이 포함됩니다.

    ```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">
      폴링은 **1.5초**에 한 번을 초과하지 마세요. 재시도 시 지수 백오프를 사용하세요. 각 계정은 `waiting` 상태의 작업을 동시에 최대 10개까지 둘 수 있습니다(`running` 작업은 포함되지 않습니다). 자세한 내용은 [제한 사항](/ko/docs/quick-start/limits)을 참고하세요.
    </Callout>
  </div>

  <div className="fd-step">
    이미지 다운로드 [#이미지-다운로드-step]

    ```bash
    curl -L "MEDIA_URL" -o output.webp
    # 또는 미디어 ID로 URL 조회 (이미지는 `urls`의 `PUBLIC`, 동영상은 `fileUrl`):
    curl "https://api.pixai.art/v2/media/batch?ids=MEDIA_ID"
    ```

    <Callout type="warn">
      생성된 이미지는 **영구적으로 보관되지 않습니다** — 작업이 완료되는 즉시 다운로드하세요.
    </Callout>
  </div>
</div>

한 번에 실행하는 스크립트 [#한-번에-실행하는-스크립트]

Python으로 생성, 폴링, 저장까지 하는 예시입니다. `requests`를 설치하고 API 키를 `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:  # 생성 직후의 작업은 잠시 404를 반환할 수 있습니다. 계속 폴링합니다.
        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)
```

다음 단계 [#다음-단계]

* [모델](/ko/docs/references/models) — 사용 가능한 모델 확인
* [Webhook](/ko/docs/references/webhook) — 폴링 없이 작업 업데이트 수신
* [예제](/ko/docs/quick-start#steps) — 이미지로 동영상 만들기, 캐릭터 일관성, 인페인팅, LoRA의 전체 스크립트
