---
title: "Start an episode"
method: POST
path: "/episodes"
tags: ["Episodes"]
---

# Start an episode

`POST /episodes`

## Request

- Base URL: `https://tryslicemedia.com/api/v1`
- URL: `https://tryslicemedia.com/api/v1/episodes`
- Auth: HTTP bearer

With source_url, Slice copies the file in from that https link (an RSS enclosure, a storage link). Without it, the answer carries a PUT upload url: upload the video, then POST /episodes/{id}/uploaded. Transcription and the clip search then start on their own. Video or audio: an audio file (MP3, M4A, AAC, WAV, OGG, Opus, FLAC) becomes an audio episode whose clips are drawn with an audio template.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `source_url` string, uri: A direct https link to the video or audio file, such as an RSS enclosure. Not a YouTube or other page.
  - `file_name` string: For an upload: the file name, used for its type (.mp4, .mov, .m4v, .webm, .mkv, .avi, .mp3, .m4a, .aac, .wav, .ogg, .opus, .flac).
  - `name` string
  - `content_type` 'podcast' | 'stream' | 'other'
  - `target_seconds` integer: How long each clip should be. Leave out for 30 to 150 seconds.

## Response `202`

Accepted

- EpisodeCreated
  - `episode_id` string
  - `name` string
  - `status` 'waiting_for_upload' | 'uploading' | 'transcribing' | 'finding_clips' | 'ready' | 'failed'
  - `livemode` boolean
  - `upload` object
    - `method` 'PUT'
    - `url` string
    - `headers` object
    - `expires_in_seconds` integer
  - `upload_page_url` string: The same upload as a page a person can open.
  - `message` string

## Other responses

- `400`: Invalid input. The message says which field.
- `401`: Missing, unknown, revoked or expired key.
- `402`: Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.
- `403`: The key lacks the permission (scope) this needs, or the account is under billing review.
- `409`: Busy, or an Idempotency-Key still running.
- `422`: Idempotency-Key reused with a different body.
- `429`: Rate limited. See retry_after and the RateLimit-* headers.

---

[API](https://skmtc.dev/tryslicemedia/apis/slice-api.md) · [All operations](https://skmtc.dev/tryslicemedia/apis/slice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tryslicemedia/apis/slice-api/revisions/3dc0b0bd8755?raw)