# BatchReel Slideshow API — Bot Guide

A focused reference for an automated agent driving the **Slideshow generator** over
the BatchReel public API. Generates vertical (1080×1920) photo decks and can
schedule them to TikTok as photo-mode (carousel) posts.

Two ways to build a deck:

1. **Auto mode (recommended)** — `POST /slideshows/auto`. Send your app
   screenshots + a brief; Grok plans the whole deck (captions, image prompts,
   where your screenshots slot in as subtle ads) plus TikTok post copy, then
   gpt-image-2 renders the generated slides.
2. **Manual mode** — `POST /slideshows`. You author every slide yourself
   (prompt or image + optional caption).

> **Access is restricted.** These endpoints are admin-only right now. They only work
> with a token belonging to the founder account (`danielt@hey.com`). Any other token
> gets `404 Not Found` — the endpoints behave as if they don't exist.

---

## 1. Base URL & auth

- **Base URL:** `https://batchreel.com/api/v1`
- **Auth:** Sanctum bearer token. Send it on every request:

```
Authorization: Bearer <YOUR_TOKEN>
Accept: application/json
Content-Type: application/json
```

**Getting a token:** sign in to BatchReel as `danielt@hey.com`, go to **Settings → API**
(`/settings/api`), and create a token. The plaintext is shown once — copy it then.
The token inherits the account's admin rights, which is what unlocks these endpoints.

**Projects:** every slideshow belongs to a project. If the account has a single
project, you can omit `project_id` and it's inferred. If it has more than one, include
`project_id` in the request body (POST) or query string (GET), or you'll get a 422.

Discover your projects with `GET /projects` — returns each project's `id`, `name`,
and connected `platforms` (pick one with `"tiktok"` if you plan to schedule):

```json
{ "data": [ { "id": 7, "name": "Faith app", "platforms": ["tiktok", "youtube"], "created_at": "…" } ] }
```

---

## 2. Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/slideshows/auto` | **Auto mode:** photos + brief in, planned deck out (async). |
| `POST` | `/slideshows/{id}/approve` | Approve (optionally edit) a plan parked in test mode → generate images. |
| `POST` | `/slideshows/{id}/replan` | Re-roll the plan with optional feedback (cheap — no image credits). |
| `POST` | `/slideshows` | **Manual mode:** author each slide yourself; generation starts immediately. |
| `GET`  | `/slideshows/{id}` | Poll one slideshow + its slides (image URLs, plan, post copy). |
| `GET`  | `/slideshows` | List recent slideshows (paginated, 50/page). |
| `POST` | `/posts` | Schedule a ready deck to TikTok as a photo-mode post (`slideshow_id`). |

There is no delete endpoint for slideshows (decks). Scheduled **posts** can be
cancelled while still `pending` with `DELETE /posts/{id}` (`{"deleted": true}`;
422 once publishing has started) — to reschedule or change settings, delete and
recreate the post; the deck is untouched and reusable.

---

## 3. Auto mode — `POST /slideshows/auto`

Send your screenshots and a brief; the planner does the rest.

### Body

| Field | Type | Notes |
|-------|------|-------|
| `brief` | string, **required** | What's in the photos / what you're promoting (≤4000 chars). |
| `direction` | string, optional | **Highest-priority override.** Theme, tone, structure, slide count, caption rules — your words beat the built-in format on any conflict. |
| `photos` | array, optional | Up to 6. Each becomes one slide, placed by the planner (usually mid-deck as a subtle ad). Omit for a fully generated deck. |
| `photos[].image_url` | string (URL) | Fetched server-side (≤25 MB). Exactly one of `image_url`/`image_b64` per photo. |
| `photos[].image_b64` | string | Inline base64 (raw or `data:` URI). |
| `photos[].pin` | int, optional | Force this photo onto slide N (1-based). Omit to let the planner place it. |
| `slide_count` | int, optional | 3–12, default 7. A default — the `direction` can override it ("only 3 slides"). |
| `test_mode` | bool, optional | Default `false`. `true` parks the run at `awaiting_review` so you can inspect/edit/re-roll the plan before image credits are spent. |
| `title` | string, optional | Internal reference; auto-named from the plan if blank. |
| `caption_position` | string, optional | `top` (default), `middle`, `bottom`, or an integer `0`–`100` = the caption panel's top edge as a percentage from the top of the frame (`30` → 30% down; `top` ≈ `10`, `bottom` ends at 90%). Clamped so the panel stays on-frame. |
| `project_id` | int, optional | Required only if the account has multiple projects. |

### Response — `202 Accepted`

The slideshow with `status: "planning"`. Poll `GET /slideshows/{id}`.

### Status flow (auto mode)

```
planning ──► pending ──► processing ──► ready        (test_mode=false)
planning ──► awaiting_review ──► pending ──► …       (test_mode=true, after approve)
planning ──► failed                                   (plan rejected — replan)
```

Planning takes ~10–30 s. Once past `planning`, the response includes:

- `plan` — the full deck plan: `slides[]` of `{type:"generated", prompt, caption}`
  or `{type:"photo", photo:N, caption}` (captions may be `null` — photos that
  speak for themselves are left clean).
- `post_title` / `post_description` — ready-to-use TikTok post copy (description
  ends with hashtags).

### Example — bible-widget deck, fully automated

```bash
curl -sS -X POST https://batchreel.com/api/v1/slideshows/auto \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "brief": "A screenshot of my Daily Bible Verse widget showing the daily verse on a phone home screen.",
    "direction": "Theme: how to add God into your daily life, with practical suggestions. My widget photo goes mid-deck as a subtle ad, no caption on it.",
    "slide_count": 7,
    "photos": [ { "image_url": "https://example.com/widget-screenshot.png" } ]
  }'
```

### Test mode: review → approve / replan

With `"test_mode": true`, the run stops at `awaiting_review`. Then:

**Inspect** the plan via `GET /slideshows/{id}` (`plan`, `post_title`, `post_description`).

**Re-roll** (repeat as needed — costs a Grok call, not image credits):

```bash
curl -sS -X POST https://batchreel.com/api/v1/slideshows/42/replan \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{ "feedback": "Punchier hooks, and move my photo one slide later." }'
```

Status returns to `planning`; poll until `awaiting_review` again. `replan` also
works on a slideshow that `failed` during planning.

**Approve** (optionally editing slides/post copy first — edit keys are **1-based
slide numbers**, the same numbering as `photos[].pin`; omit anything you don't
want to change. An unknown slide number is a 422, not a silent no-op):

```bash
curl -sS -X POST https://batchreel.com/api/v1/slideshows/42/approve \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "post_title": "5 tiny habits that changed my mornings",
    "slides": { "2": { "caption": "Start with one verse before your feed" } }
  }'
```

Image generation starts; poll until `ready`.

---

## 4. Manual mode — `POST /slideshows`

### Body

| Field | Type | Notes |
|-------|------|-------|
| `title` | string, optional | For your own reference only. |
| `caption_position` | string, optional | `top` (default), `middle`, `bottom`, or an integer `0`–`100` = the caption panel's top edge as a percentage from the top (`30` → 30% down; `top` ≈ `10`, `bottom` ends at 90%). Clamped on-frame. Applies to every captioned slide. |
| `size` | string, optional | gpt-image-2 generation size: `1024x1536` (default, portrait), `1024x1024`, `1536x1024`, or `auto`. All slides are cropped to 1080×1920 regardless. |
| `slides` | array, **required** | 1–12 slides. |
| `slides[].prompt` | string, optional | Image prompt (≤2000 chars). Used when no image is supplied. |
| `slides[].image_url` | string (URL), optional | Use your own image instead of generating. Fetched server-side (≤25 MB). |
| `slides[].image_b64` | string, optional | Inline base64 image (raw or `data:` URI) instead of generating. |
| `slides[].caption` | string, optional | Caption text burned onto the slide (≤600 chars). Omit for no caption. |
| `project_id` | int, optional | Required only if the account has multiple projects. |

Slides keep the order you submit them in — `position` equals the array index,
regardless of whether each slide is a prompt or an image.

**Each slide must have exactly one source:** a `prompt`, an `image_url`, or an
`image_b64`. If a slide has none, the request fails with 422. If an image is supplied,
it wins and any `prompt` on that slide is ignored.

Returns `202 Accepted` with everything `pending`; poll the show endpoint.

### Example — generate slides from prompts

```bash
curl -sS -X POST https://batchreel.com/api/v1/slideshows \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "title": "Corgi facts",
    "caption_position": "top",
    "slides": [
      { "prompt": "A photorealistic corgi running on a sunset beach, vertical", "caption": "POV: your dog runs the beach" },
      { "prompt": "A photorealistic corgi asleep in a cozy bed, soft morning light", "caption": "...then naps all day" }
    ]
  }'
```

---

## 5. Poll a slideshow — `GET /slideshows/{id}`

Call this repeatedly until `status` is `ready`, `awaiting_review` (test mode), or `failed`.

```json
{
  "data": {
    "id": 42,
    "title": "Morning faith habits",
    "status": "ready",
    "mode": "auto",
    "error": null,
    "caption_position": "top",
    "size": "1024x1536",
    "plan": { "title": "…", "slides": [ { "type": "generated", "prompt": "…", "caption": "…" }, { "type": "photo", "photo": 1, "caption": null } ] },
    "post_title": "5 tiny habits that changed my mornings",
    "post_description": "Small ways to keep God close all day… #faith #dailyhabits #bibleverse #christiantiktok",
    "slides": [
      { "position": 0, "status": "ready", "caption": "…", "url": "https://…spaces…/slide-0.png?signature=…", "error": null }
    ],
    "created_at": "2026-07-10T22:10:00+00:00"
  }
}
```

### Status values

- **Slideshow `status`:** `planning` → (`awaiting_review` →) `pending` → `processing` →
  `ready` (all slides done; some may still be `failed`) or `failed`.
- **Slide `status`:** `pending` → `processing` → `ready` (then `url` is set) or `failed`
  (then `error` explains why).

### Image URLs

Each ready slide's `url` is a **presigned link valid for ~1 hour**. Download it within
that window, or just re-GET the slideshow to mint fresh URLs. Images are PNG, 1080×1920.

### Polling guidance

Poll every 3–5 seconds. Planning takes ~10–30 s; generation typically takes ~15–60 s
**per slide** (gpt-image-2, high quality), running a few slides in parallel. A 6-slide
deck is usually done within a couple of minutes. Treat `status: failed` as terminal for
generation, but a planning failure can be retried with `POST /slideshows/{id}/replan`.

---

## 6. Schedule the deck to TikTok — `POST /posts`

Once a deck is `ready`, schedule it as a **TikTok photo-mode (carousel) post**
via the regular posts endpoint, passing `slideshow_id` instead of `video_id`:

```bash
curl -sS -X POST https://batchreel.com/api/v1/posts \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "slideshow_id": 42,
    "platforms": ["tiktok"],
    "scheduled_at": "2026-07-12T09:00:00",
    "timezone": "America/Chicago",
    "tiktok_privacy_level": "PUBLIC_TO_EVERYONE",
    "tiktok_allow_comment": true
  }'
```

Notes:

- `platforms` must be `["tiktok"]` — photo posts are TikTok-only for now.
- The slideshow must be `ready` (422 otherwise).
- **Direct photo posts work** (the app's TikTok audit cleared 2026-08-21) —
  omit `tiktok_draft` for fully automatic publishing. Pass `tiktok_draft: true`
  only when you want the deck in the account's TikTok inbox for a human to
  review and post in-app; those targets finish as `staged`, not `published`.
- **TikTok post settings** are accepted on this endpoint and you should set
  them explicitly — interactions default to **off** (TikTok requires explicit
  opt-in, so an omitted field means "not allowed"):
  - `tiktok_privacy_level` — `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`,
    `FOLLOWER_OF_CREATOR`, or `SELF_ONLY`. Omit to auto-pick the most public
    level the creator's account allows.
  - `tiktok_allow_comment`, `tiktok_allow_duet`, `tiktok_allow_stitch` —
    booleans, default `false`. For photo posts duet/stitch don't apply.
  - `tiktok_brand_organic`, `tiktok_brand_content` — commercial-content
    disclosure booleans, default `false`. `tiktok_brand_content` can't be
    combined with `SELF_ONLY` privacy (422).
- `title` and `caption` are optional — they **default to the deck's
  `post_title` and `post_description`** (title is TikTok's photo-post title,
  caption is the description with hashtags). Override either explicitly if
  you want different copy.
- Omit `scheduled_at` to post at the next scheduler tick (~1 min).
- All slides that finished (`ready`) are included, in order; the first slide
  is the cover image. TikTok adds background music automatically
  (`auto_add_music`) on direct posts.
- The response is the standard post envelope (now with `type` and
  `slideshow_id`); poll `GET /posts/{id}` and read `targets[].status` —
  `published` when live, `failed` with `error` otherwise.

---

## 7. List slideshows — `GET /slideshows`

Paginated (50 per page), newest first. Standard Laravel pagination envelope:

```json
{
  "data": [ { "id": 42, "status": "ready", "slides": [ ... ], ... } ],
  "links": { "next": "https://batchreel.com/api/v1/slideshows?page=2", "...": "..." },
  "meta": { "current_page": 1, "last_page": 1, "total": 7 }
}
```

---

## 8. Errors

| Code | Meaning |
|------|---------|
| `401 Unauthorized` | Missing/invalid bearer token. |
| `404 Not Found` | Token is valid but **not the admin account**, or the slideshow id isn't yours. (Admin-gating returns 404 by design.) |
| `422 Unprocessable Entity` | Validation failed — e.g. missing `brief`, a manual slide with no prompt/image, >12 slides, approving a plan that isn't `awaiting_review`, scheduling a deck that isn't `ready`, or `project_id` needed. The body lists the offending fields. |

---

## 9. End-to-end recipe for the bot

Fully automated:

1. `POST /slideshows/auto` with screenshots + brief (+ direction) → grab `data.id`.
2. Poll `GET /slideshows/{id}` every 3–5 s until `status` is `ready` (or `failed` → `replan`).
3. `POST /posts` with `slideshow_id` + `platforms: ["tiktok"]` + `scheduled_at`.
4. Poll `GET /posts/{id}` until the tiktok target is `published`.

With review (recommended while honing prompts):

1. `POST /slideshows/auto` with `"test_mode": true`.
2. Poll until `awaiting_review`; inspect `plan` / `post_title` / `post_description`.
3. `POST /slideshows/{id}/replan` with feedback until the plan looks right.
4. `POST /slideshows/{id}/approve` (optionally with edits) → poll until `ready`.
5. Schedule via `POST /posts` as above.
