첫 번째 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)