# API Reference (/docs/api)



The Jellypod API gives developers programmatic access to the core
platform: creating AI podcast hosts, browsing voices, uploading
research sources, and generating episodes or entire podcast series.

<Callout type="info">
  Use the [Jellypod API skill](https://github.com/Jellypod-Inc/skills) to generate podcasts from your AI coding assistant:

  ```
  npx skills add Jellypod-Inc/skills --skill jellypod-api
  ```
</Callout>

## Credits & Usage [#credits--usage]

The API uses the same credit system as the Jellypod app. Generating
an episode through the API costs the same credits as generating one
in the studio. Credits are deducted from your organization's
balance and count toward your plan's usage limits. See
[Understanding Credits](/docs/help/getting-started/understanding-credits)
for details.

## Importing Script Text [#importing-script-text]

`POST /episodes/import` accepts script or transcript text, resolves bracketed
speaker labels to hosts, creates missing hosts when needed, and queues a new
episode for generation. Use this when you have the episode content but do not
want to manually split it into chapters and host segments.

```json
{
  "podcast_id": "podcast_id",
  "script": "[Host One]\nWelcome to the show. Today we're talking about how small daily habits can make a big difference.\n\n[Host Two]\nI love that topic. Let's start with the easiest habit someone can try this week."
}
```

Jellypod infers the host set from the bracketed speaker labels and the
podcast's assigned hosts. Unmatched speaker labels always create new hosts
automatically; the response includes `magic_created_host_ids` listing any
hosts that were added by this import. Imported content is capped at 75,000
characters. The generated episode goes through credit preflight, weighted
generation rate limiting, and asynchronous rendering. Poll
`GET /episodes/{episode_id}`; when the job completes, the response includes
the available download URLs.

## Generating From A Script [#generating-from-a-script]

`POST /episodes/generate` can create an episode from either a prompt or a
structured script. Script mode skips prompt-based script writing and uses your
provided chapters and segments directly.

Use `GET /hosts` to fetch the `host_id` values available to your organization.
Every segment must reference one of those hosts. Imported script text is capped
at 75,000 total characters across all segments.

```jsonc
{
  "podcast_id": "podcast_id",
  "script": {
    "chapters": [
      {
        "title": "Introduction",
        "segments": [
          {
            "host_id": "host_id_1",
            "text": "Welcome to the show. Today we're talking about how small daily habits can make a big difference."
          },
          {
            "host_id": "host_id_2",
            "text": "I love that topic. Let's start with the easiest habit someone can try this week.",
            "speed": 1 // Optional. Defaults to 1.
          }
        ]
      }
    ]
  }
}
```

The example is annotated as JSONC so the optional field can be called out. Send
valid JSON in API requests.

Rules for script generation:

* Send either `prompt` or `script`, not both.
* `source_ids` are only supported for prompt-based generation.
* Prompt-generation options such as `web_search` and `episode_length` are not
  used in script mode.
* Segment `speed` is optional, defaults to `1`, and accepts values from `0.5`
  to `2`.
* Scripts can include up to 50 chapters, 200 segments per chapter, and 600
  segments total. Each segment can contain up to 5,000 characters.
* Long scripts require enough available credits before generation starts. The
  final charge is still based on the rendered audio duration.
* Script generation creates a new episode.

## Authentication [#authentication]

All requests require a Jellypod API key passed via the `Authorization` header:

```
Authorization: Bearer sk_...
```

API keys are organization-scoped. You can <a href="https://studio.jellypod.com/settings/api-keys" target="_blank" rel="noopener">create and manage API keys</a> from the Jellypod
dashboard under **Settings → API Keys**.

## Base URL [#base-url]

```
https://api.jellypod.com/v1
```

Browse the endpoints in the sidebar to get started.