빠른 시작

첫 번째 API 호출

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

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

인증: 모든 요청에 Authorization: Bearer YOUR_API_KEY 헤더를 추가하세요. API 키 발급 방법은 PixAI API를 사용하려면?을 참고하세요.

단계

작업 제출

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

응답:

{
  "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입니다.

modelVersionId는 PixAI의 모델 버전 URL https://pixai.art/model/<id>/<modelVersionId>에서 마지막 세그먼트입니다. 추천 모델은 모델을 참고하세요.

상태 폴링

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

curl https://api.pixai.art/v2/task/TASK_ID \
  -H "Authorization: Bearer $PIXAI_API_KEY"
상태의미
waiting작업이 대기 중
running생성 진행 중
completed완료, 결과물 준비됨
failed생성 실패
cancelled작업이 취소됨

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

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

폴링은 1.5초에 한 번을 초과하지 마세요. 재시도 시 지수 백오프를 사용하세요. 각 계정은 waiting 상태의 작업을 동시에 최대 10개까지 둘 수 있습니다(running 작업은 포함되지 않습니다). 자세한 내용은 제한 사항을 참고하세요.

이미지 다운로드

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

생성된 이미지는 영구적으로 보관되지 않습니다 — 작업이 완료되는 즉시 다운로드하세요.

한 번에 실행하는 스크립트

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

다음 단계

  • 모델 — 사용 가능한 모델 확인
  • Webhook — 폴링 없이 작업 업데이트 수신
  • 예제 — 이미지로 동영상 만들기, 캐릭터 일관성, 인페인팅, LoRA의 전체 스크립트