개발자

1 · 인증

프로필 → API 키에서 "po_…" 키를 발급하세요(오피스 소유자만 가능). 요청마다 X-API-Key 헤더로 보내세요 — 키는 생성할 때 딱 한 번만 보여요.

2 · brief 대기열에 넣기

POST /api/v1/runs — 202를 반환해요. 실행은 비동기예요. 필드: pixmate_slug, brief (20,000자 이하), locale (tr|en).

curl -X POST https://pixel-office-api-production.up.railway.app/api/v1/runs \
  -H "X-API-Key: po_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "pixmate_slug": "ava-generalist-marketer",
    "brief": "Yeni single için 6 sosyal medya postu yaz",
    "locale": "tr"
  }'
# → 202 Accepted
# { "id": "…", "status": "queued", "pixmate_slug": "ava-generalist-marketer", … }

3 · 결과 가져오기

GET /api/v1/runs (liste) · GET /api/v1/runs/{id}

curl https://pixel-office-api-production.up.railway.app/api/v1/runs/RUN_ID \
  -H "X-API-Key: po_XXXXXXXXXXXXXXXX"
# status: queued → running → completed | failed

4 · 요청 한도

키당 분당 60회 요청. 초과하면 429 + Retry-After가 오고, 모든 응답에 X-RateLimit-Limit / X-RateLimit-Remaining 헤더가 들어 있어요.

5 · Webhooks

프로필 → Webhooks에서 HTTPS 엔드포인트를 등록하세요. 실행이 종료 상태(completed/failed/cancelled)가 되면 서명된 POST가 전송돼요. 3회 시도(0/5/25초). 서명: HMAC-SHA256("{timestamp}.{gövde}").

API 키로 구독할 수도 있습니다(Zapier/Make “REST hook”): POST /api/v1/webhooks {"url": "https://…"} 는 서명 키를 한 번만 돌려주고, GET /api/v1/webhooks 는 목록을, DELETE /api/v1/webhooks/{id} 는 구독을 해지합니다.

{
  "event": "run.completed",          // ya da run.failed / run.cancelled
  "run": {
    "id": "…", "status": "completed",
    "pixmate_slug": "ava-generalist-marketer", "kind": "chat",
    "tokens_consumed": 3,
    "error_message": null, "session_id": "…",
    "created_at": "…", "finished_at": "…"
  },
  "sent_at": "…"
}

검증 (Python):

import hashlib, hmac

def verify(secret: str, ts: str, raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# headers: X-Webhook-Timestamp / X-Webhook-Signature