---
title: "Generate a new episode (asynchronous)"
method: POST
path: "/v1/episodes/generate"
tags: ["Episodes"]
---

# Generate a new episode (asynchronous)

`POST /v1/episodes/generate`

## Request

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

## Headers

- `idempotency-key` string: Optional key for one logical generation command. Reuse the same key and input after a lost or uncertain response. After a proven rejection before work starts, follow recovery.idempotency_key. Omit it to start a new generation on every request.

## Request body

- GenerateEpisodeInput: Fields for generating a new episode asynchronously. Prompt mode always writes a new script from the supplied material. Use POST /v1/episodes/import to preserve script text, or script mode here for a validated structured script.
  - `host_ids` string[]: Hosts to use for generation. In script mode, every segment host_id must be included here, or omit host_ids to infer them from the script.
  - `options` object: Prompt-mode generation options. These are not used when `script` is provided.
    - `episode_length` string
    - `episode_length_minutes` integer
    - `web_search` boolean
  - `prompt` string: Prompt used to write the episode script. Provide either `prompt` or `script`, not both.
  - `script` ImportedEpisodeScript: Structured script input for episode generation. Script mode skips prompt-based script writing. Limits: 75000 total text characters, 50 chapters, 200 segments per chapter, 600 total segments, and 5000 characters per segment.
    - `chapters` ImportedScriptChapter[], required: Ordered script chapters. Maximum 50 chapters.
      - `segments` ImportedScriptSegment[], required: Spoken turns in this chapter. Maximum 200 segments.
        - `host_id` string, required: Host ID for the speaker of this segment.
        - `text` string, required: Text to synthesize for this segment. Maximum 5000 characters.
      - `title` string: Optional chapter title.
  - `source_ids` string[]: Source documents for prompt-based generation. Not supported when `script` is provided.
  - `podcast_id` string, uuid, required: Podcast that will own the generated episode.
  - `render` boolean: Render audio and video after generation only when explicitly requested. Defaults to false, leaving an editable draft. Generation uses credits; rendering is free.

## Response `202`

Episode queued for generation

- AcceptedEpisodeResponse: Acknowledgement for an asynchronously-generated episode.
  - `data` object, required
    - `created_at` string, required
    - `host_ids` string[], required
    - `id` string, required
    - `podcast_id` string, required
    - `status` 'generating', required
    - `updated_at` string, required
    - `workflow_run_id` string, required

## Other responses

- `400`: Validation failed or malformed request.
- `401`: Missing or invalid API key.
- `403`: Authenticated, but this API key does not have access to this resource.
- `404`: Resource not found.
- `415`: Request `Content-Type` is not supported for this endpoint.
- `429`: Rate limit exceeded. Response includes `Retry-After`, `RateLimit`, and `RateLimit-Policy` headers (IETF draft).
- `500`: Internal server error.
- `502`: The API could not enqueue the downstream asynchronous workflow.

---

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