# Series

A series is a set-and-forget channel: it generates a new faceless video on a schedule and can auto-post each episode to connected accounts. Creating a series is free; each generated episode charges the credit cost of its model (20 to 100 credits), exactly like a single video.

## Create a series (POST /series, scope series:write)

Required: `name`, `source`, and a `niche` or `customPrompt`. Everything else is optional and gets product defaults. Enumerate valid values first: `GET /options?kind=sources`, `?kind=niches`, `?kind=styles`, `?kind=languages`, `?kind=backgrounds`, `?kind=music`, `?kind=captionThemes`, and `GET /voices`.

```bash
curl -s -X POST https://faceless.so/api/v1/series \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Deep sea facts",
    "source": "Facts & stories",
    "niche": "Ocean facts",
    "voice": "EXAVITQu4vr4xnSDxMaL",
    "duration": "60",
    "autoPostTime": "18:00",
    "timezone": "America/New_York"
  }'
```

The first episode starts generating right after creation. Useful optional fields:

- `destination` and `destinationAccounts`: auto-post platform and connected account ids (from `GET /accounts`)
- `postingDays`: e.g. `["Monday", "Wednesday", "Friday"]`; omit for every day
- `brollModel`: `storyboard`, `motion_lite` or `motion_pro`, which sets the per-episode credit cost
- `subreddit`: when `source` is `"Reddit post"`
- `backgroundVideo` or `useRandomBackgroundVideo`: gameplay/footage behind the captions
- `captionStyle`, `showEmojis`, `enableBackgroundMusic`, `backgroundMusicMood`, `hashtags`, `tone`, `youtubePrivacyStatus`

Rate limit: 5 series creations per 300s per key.

## Track episodes (GET /series/{id}/episodes, scope series:read)

Episodes are regular videos plus scheduling state. Newest first, paginated:

```bash
curl -s "https://faceless.so/api/v1/series/665f1b2a9c31a2b3c4d5e901/episodes?limit=10" \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

```json
{
  "success": true,
  "data": [{ "id": "665f1b2a9c31a2b3c4d5eb01", "projectId": "665f1b2a9c31a2b3c4d5ea01", "status": "posted", "scheduledTime": "2026-07-30T18:00:00.000Z" }],
  "pagination": { "page": 1, "limit": 10, "total": 1 }
}
```

Poll an episode's generation with `GET /videos/{projectId}/status` like any other video.

## Force the next episode now (POST /series/{id}/generate, scope series:write)

Generates the next episode immediately instead of waiting for the schedule. Charges the series' per-episode cost. Returns the new `projectId` and its `statusUrl`. Rate limit: 5 per 300s.

```bash
curl -s -X POST https://faceless.so/api/v1/series/665f1b2a9c31a2b3c4d5e901/generate \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Update, pause, delete

- `GET /series` and `GET /series/{id}` (scope series:read): list and inspect configuration.
- `PATCH /series/{id}` (scope series:write): change any subset of fields; only the fields you send change. Pass `{"paused": true}` to pause automatic generation, `false` to resume.
- `DELETE /series/{id}` (scope series:write): stops all future generation; already-generated videos are kept.

```bash
curl -s -X PATCH https://faceless.so/api/v1/series/665f1b2a9c31a2b3c4d5e901 \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoPostTime": "09:00", "paused": false}'
```

## Budgeting

An everyday series on `storyboard` spends 20 credits per episode: a daily series is about 600 credits per month, a Monday/Wednesday/Friday series about 260. Check the balance with `GET /credits` before creating aggressive schedules; an episode that cannot be paid for fails with `insufficient_credits`. See [credits and limits](/developers/docs/credits-and-limits).