# Ensemble REST API v1

ה-API של Ensemble נותן לכל שרת את מה שהאפליקציה עושה: יצירת תמונות וסרטונים, הספרייה, המוח,
המשרד ומפל התוכן. אותם מחירים, אותו ספר קרדיטים, אותם שערים ואותה הפרדה בין חשבונות.
האישורים של תוצרי המשרד נשארים באפליקציה.

- **בסיס:** `https://<הדומיין שלכם>/api/v1`
- **אימות:** `Authorization: Bearer ens_live_…` (מפתח מ-`/account/developers`)
- **פורמט:** JSON בבקשה ובתשובה. אין עוגיות: הדפדפן לא מעביר הרשאה ל-API.
- **מגבלת קצב:** 60 בקשות לדקה לכל מפתח (כולל קריאות MCP). מעבר למגבלה: `429` עם `Retry-After`.

## מפתחות

- מפתח נראה כך: `ens_live_` ואחריו 32 תווים (base62). הוא מוצג **פעם אחת**, ביצירה.
- אנחנו שומרים רק את ה-SHA-256 שלו ואת 13 התווים הראשונים (`ens_live_AbCd`) כדי להבחין בין מפתחות.
- עד 10 מפתחות פעילים לחשבון. ביטול מיידי בהגדרות המפתחים.
- הרשאות (scopes):

| scope | מה מותר |
|---|---|
| `read` | כל ה-GET: חשבון, יצירות, נכסים, המוח, מפל |
| `generate` | הצעת מחיר ויצירת תמונות וסרטונים (מוציא קרדיטים) |
| `office` | הצעת מחיר והפעלת בריף במשרד (מוציא קרדיטים) |
| `cascade` | הצעת מחיר והפעלת מפל תוכן (מוציא קרדיטים) |

## שגיאות

כל שגיאה חוזרת באותו מבנה, עם הודעה בעברית שמיועדת לאנשים:

```json
{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "…" } }
```

| סטטוס | קודים |
|---|---|
| 400 | `INVALID`, `UNKNOWN_MODEL`, `UNPRICED`, `BAD_REQUEST` |
| 401 | `UNAUTHORIZED` (חסר, שגוי או בוטל) |
| 402 | `INSUFFICIENT_CREDITS` (שום דבר לא נגבה) |
| 403 | `FORBIDDEN_SCOPE`, `PLAN_REQUIRED` |
| 404 | `NOT_FOUND` (גם מזהה של חשבון אחר) |
| 409 | `CONCURRENCY`, `MODEL_DISABLED` |
| 429 | `RATE_LIMITED` |
| 503 | `NOT_CONFIGURED`, `MODEL_UNAVAILABLE`, `AGENTS_NOT_CONFIGURED` |

## נקודות קצה

### `GET /me` · read
החשבון שמאחורי המפתח.

```bash
curl https://<domain>/api/v1/me -H "Authorization: Bearer $ENSEMBLE_KEY"
```

```json
{
  "user": { "id": "…", "email": "…", "name": "…" },
  "plan": { "id": "starter", "name": "…" },
  "credits": { "subscription": 400, "topup": 120, "total": 520 },
  "key": { "id": "…", "name": "Claude Desktop", "prefix": "ens_live_AbCd", "scopes": ["read", "generate"] },
  "models": [{ "id": "image-draft", "surface": "image", "label": "תמונה · טיוטה" }],
  "links": { "office": "https://<domain>/office", "billing": "https://<domain>/account/billing" }
}
```

### `POST /generations/quote` · generate
כמה תעלה יצירה. שום דבר לא נגבה. אותו גוף כמו `POST /generations`.

```bash
curl https://<domain>/api/v1/generations/quote \
  -H "Authorization: Bearer $ENSEMBLE_KEY" -H "Content-Type: application/json" \
  -d '{"type":"image","prompt":"עוגת גבינה על שיש לבן, אור בוקר","aspectRatio":"4:5"}'
```

```json
{ "quote": { "model": "image-draft", "surface": "image", "credits": 6, "balance": 520, "affordable": true } }
```

### `POST /generations` · generate
יוצר תמונה או וידאו, ומחזיר `202` כשהיצירה רצה ברקע.

| שדה | סוג | הערות |
|---|---|---|
| `type` | `"image"` \| `"video"` | חובה |
| `prompt` | string | חובה, עד 12,000 תווים. עובדות המוח המאושרות מתווספות אוטומטית |
| `quality` | `"draft"` \| `"final"` | ברירת מחדל `draft` |
| `model` | string | מזהה מ-`/me` (`video-kling`, `video-seedance`…). גובר על `quality` |
| `aspectRatio` | string | תמונה: `1:1` `4:5` `9:16` `16:9`. וידאו: `9:16` `16:9` |
| `duration` | number | וידאו: 4, 6 או 8 שניות |
| `media` | `[{ role, url }]` | תמונות או יצירות **שלכם** (`role: "start"` מנפיש תמונה כפריים ראשון) |
| `useBrain` | boolean | ברירת מחדל: פעיל כשיש עובדות מאושרות |
| `projectId` | string | פרויקט בספרייה |

**Idempotency:** שלחו `Idempotency-Key` (עד 200 תווים). אותו מפתח פעמיים מאותו חשבון = יצירה אחת וחיוב אחד,
גם אם הבקשה השנייה הגיעה דרך MCP.

```bash
curl https://<domain>/api/v1/generations \
  -H "Authorization: Bearer $ENSEMBLE_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: autumn-sale-reel-1" \
  -d '{"type":"video","prompt":"עוגה מסתובבת באור בוקר","duration":6,"aspectRatio":"9:16"}'
```

```json
{ "generation": { "id": "…", "status": "queued", "cost": 60, "surface": "video", "outputs": [] } }
```

### `GET /generations/:id` · read
סטטוס (`queued`, `in_progress`, `completed`, `failed`, `nsfw`, `canceled`), עלות, החזר ו-`outputs[].url`.
יצירה שנכשלה מזוכה אוטומטית. בדקו כל כמה שניות; סרטון לוקח דקות.

### `GET /assets?type=image|video&limit=24&cursor=` · read
התמונות והסרטונים המוכנים, מהחדש לישן. `nextCursor` לעמוד הבא.

### `GET /brain/facts` · read
העובדות **המאושרות** במוח בלבד (עובדות שממתינות לאישור לא יוצאות מהאפליקציה).

```json
{ "facts": [{ "id": "…", "folder": "offer", "key": "ההצעה", "value": "עוגות גבינה אפויות כל בוקר", "approvedAt": 1792300000000 }] }
```

### `POST /office/briefs/quote` · office
עמלת הריצה (`fee`) ועלות המדיה המינימלית (`media`, טיוטות). `credits = fee + media` היא היתרה שנדרשת להתחלה.

### `POST /office/briefs` · office
מתחיל ריצה במשרד, עם אותן עמלות, אותן מגבלות (3 ריצות פעילות, 12 לשעה) ואותם שערי תוכנית כמו באפליקציה.
כל תוצר מחכה לאישור שלכם במשרד.

```bash
curl https://<domain>/api/v1/office/briefs \
  -H "Authorization: Bearer $ENSEMBLE_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"קמפיין לידים לקונדיטוריה בגוש דן","budgetPerDay":150,"imageCount":5,"wantsVideo":false}'
```

שדות: `goal` (חובה), `budgetPerDay` (לא חובה, ₪; בלעדיו בעל העסק קובע תקציב בסוף, בכרטיס הקמפיין), `audienceHint`, `channels` (`facebook`, `instagram`),
`imageCount` (3/5/8), `wantsVideo`, `includeAnalyst`, `landingPage` (תוכנית Ultra).

```json
{ "run": { "id": "…", "status": "queued", "goal": "…" }, "officeUrl": "https://<domain>/office", "note": "…" }
```

### `POST /cascade/quote` · cascade
עלות הטקסט והמדיה לכל פורמט, וסך הכול (`credits`).

### `POST /cascade` · cascade
מקור אחד לכמה פורמטים. מחזיר `202` עם היחידות בתור, וכותב אותן ברקע.

```bash
curl https://<domain>/api/v1/cascade \
  -H "Authorization: Bearer $ENSEMBLE_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"kind":"text","text":"מבצע סתיו: 20% הנחה על כל עוגות הגבינה עד סוף החודש"},"formats":["instagram","linkedin","whatsapp"],"media":["instagram"]}'
```

`source`: `{ "kind": "text", "text" }` או `{ "kind": "generation" | "asset" | "run", "id" }`.
`formats`: `linkedin`, `instagram`, `carousel`, `story`, `reel`, `facebook`, `newsletter`, `whatsapp`,
`google_ads`, `image_ad`, `blog`, `x`.

### `GET /cascade/:id` · read
המפל והיחידות שלו: `status` לכל יחידה ו-`content` כשהיא מוכנה.

## שימוש

בהגדרות המפתחים רואים לכל מפתח את השימוש האחרון, את מספר הבקשות החודש ואת הקרדיטים שהוצאו דרכו החודש.