Skip to content
Jellypod
Esc
↑↓navigate↵open⌘Jpreview

Generate a new episode (asynchronous)

POST/v1/episodes/generate
Authorization
AuthorizationBearer token · headerrequired

API key issued from /settings/api-keys in the Jellypod studio. Send as Authorization: Bearer <key>.

Header parameters
idempotency-keystring

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.

min length 1 · max length 255 · matches ^[\x21-\x7e]+$
Request body
requiredapplication/json
host_idsstring[]

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.

languagestring
Allowed:enesfrhiptzhdejaarrukoiditnltrplsvfilmsroukelcsdafinobghrsktaaceafaksqamhyasawaazbanbjnbaeubebembnbhobsbugmyyuecackbhnenycrhdyudzetgllgkagnguhthahehuisiggajvkabkamknkskkkmkirwkgkyloltglvltlbmkmagmaimlmtmnimrminlusmnnensoorpagpsfapasatsrsdsislsoswsstgtethtiuruguzvicy
optionsobject

Prompt-mode generation options. These are not used when script is provided.

default: {}
Show properties
episode_lengthstring
episode_length_minutesinteger
min 1 · max 75
web_searchboolean
promptstring

Prompt used to write the episode script. Omit it to write the episode from source_ids alone. Provide prompt, source_ids, or both, or script instead.

min length 10 · max length 10000
scriptImportedEpisodeScript

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.

Show properties
chaptersImportedScriptChapter[]required

Ordered script chapters. Maximum 50 chapters.

min items 1 · max items 50
Show properties
Array of ImportedScriptChapter
segmentsImportedScriptSegment[]required

Spoken turns in this chapter. Maximum 200 segments.

min items 1 · max items 200
Show properties
Array of ImportedScriptSegment
host_idstringrequired

Host ID for the speaker of this segment.

min length 1
textstringrequired

Text to synthesize for this segment. Maximum 5000 characters.

min length 1 · max length 5000
titlestring

Optional chapter title.

min length 1 · max length 200
source_idsstring<uuid>[]

Source documents for prompt-based generation. Not supported when script is provided.

podcast_idstring<uuid>required

Podcast that will own the generated episode.

outputsstring[]

Files to produce: audio (MP3), video (MP4 with sound), both, or [] for an editable draft. Each requested file becomes downloadable independently. Do not combine with render. Omission preserves legacy render behavior.

max items 2
renderbooleandeprecated

Deprecated: use outputs. True produces audio and video; false or omission leaves an editable draft. Do not combine with outputs.

Responses
202

Episode queued for generation

dataobjectrequired
Show properties
created_atstringrequired
host_idsstring[]required
idstringrequired
podcast_idstringrequired
statusstringrequired
Allowed:generating
updated_atstringrequired
workflow_run_idstringrequired
400

Validation failed or malformed request.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
401

Missing or invalid API key.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
403

Authenticated, but this API key does not have access to this resource.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
404

Resource not found.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
415

Request Content-Type is not supported for this endpoint.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
429

Rate limit exceeded. Wait Retry-After seconds before retrying; RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset describe the window.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
500

Internal server error.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
502

The API could not enqueue the downstream asynchronous workflow.

detailstring

Longer human-readable explanation when available.

errorsobject[]

Per-field validation failures. Present when type is validation_error.

Show properties
Array of object
fieldstringrequired
messagestringrequired
reasonstring

Script import failure when one or more Speakers have no saved Character match.

Allowed:unresolved_speakers
recoveryobject
Show properties
actionstringrequired
Allowed:correct_inputchoose_characterscheck_accountpoll_contentopen_studiocheck_contentreconnectretrycheck_result
idempotency_keystring
Allowed:reusenew
poll_after_secondsnumber
min 0
toolstring
Allowed:list_characterslist_contentget_contentsave_podcast
request_idstring

Correlation id, also returned in the X-Request-Id response header. Include in support requests.

speakersstring[]

Speaker labels needing a saved Character match when reason is unresolved_speakers.

statusintegerrequired

HTTP status code mirrored from the response.

titlestringrequired

Short human-readable summary.

typestringrequired

Machine-readable error class. Suitable for switch/match in client code.

Allowed:bad_requestvalidation_errorunauthorizedforbiddennot_foundconflictmethod_not_allowedunsupported_media_typeunprocessable_entityrate_limitedbad_gatewayinternal_error
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.jellypod.com/v1/episodes/generate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "host_ids": [
    "2e6939fe",
    "a91c4d22"
  ],
  "language": "en",
  "options": {},
  "prompt": "Create a friendly two-host episode about simple habits for a calmer workweek.",
  "script": {
    "chapters": [
      {
        "segments": [
          {
            "host_id": "2e6939fe",
            "text": "Welcome to the show. Today we are talking about one small habit that can make the week easier."
          },
          {
            "host_id": "a91c4d22",
            "text": "I like that. Let us start with something simple someone can try tomorrow morning."
          }
        ],
        "title": "Opening"
      }
    ]
  },
  "source_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "podcast_id": "4c1cb0f8-818b-4f7a-9ddb-0d1ea990b35a",
  "outputs": [
    "audio"
  ],
  "render": true
}'
Response
{
  "data": {
    "created_at": "string",
    "host_ids": [
      "string"
    ],
    "id": "string",
    "podcast_id": "string",
    "status": "generating",
    "updated_at": "string",
    "workflow_run_id": "string"
  }
}

Was this page helpful?