Entwickler

1 · Authentifizierung

Erzeuge unter Profil → API-Schlüssel einen "po_…"-Schlüssel (nur Office-Inhaber). Sende ihn im X-API-Key-Header — der Schlüssel wird bei der Erstellung nur EINMAL gezeigt.

2 · Briefing einreihen

POST /api/v1/runs — gibt 202 zurück; die Ausführung läuft async. Felder: pixmate_slug, brief (≤20.000 Zeichen), locale (tr|en).

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

3 · Ergebnis abrufen

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

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

4 · Rate-Limits

60 Anfragen pro Minute und Key. Bei Überschreitung 429 + Retry-After; jede Antwort trägt die Header X-RateLimit-Limit / X-RateLimit-Remaining.

5 · Webhooks

Registriere unter Profil → Webhooks einen HTTPS-Endpoint. Erreicht ein Run einen Endzustand (completed/failed/cancelled), kommt ein signierter POST; 3 Versuche (0/5/25 Sek.). Signatur: HMAC-SHA256("{timestamp}.{body}").

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

Verifizierung (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