开发者

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