Create a video

POST/v1/videos

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_idstring

Narrator Host ID. Required unless host_ids is given. Do not combine with host_ids.

min length 1

languagestring

Narration language code. Defaults to en.

Allowed:enesfrhiptzhdejaarrukoiditnltrplsvfilmsroukelcsdafinobghrsktaaceafaksqamhyasawaazbanbjnbaeubebembnbhobsbugmyyuecackbhnenycrhdyudzetgllgkagnguhthahehuisiggajvkabkamknkskkkmkirwkgkyloltglvltlbmkmagmaimlmtmnimrminlusmnnensoorpagpsfapasatsrsdsislsoswsstgtethtiuruguzvicy

orientationstring

Output orientation. Omit for AUTO, which follows the product policy.

Allowed:AUTOPORTRAITLANDSCAPESQUARE

promptstring

Instructions for writing new narration: describe the story, audience, and desired result. Omit it to write from the attached sources alone. To preserve finished narration word for word, use script instead.

min length 1 · max length 20000

scriptstring

Finished plain-text narration. Put [Character Name] on its own line before each turn. Speaker labels resolve to saved Characters unless speaker_characters assigns their IDs, and may resolve to at most 4 distinct Characters.

min length 1 · max length 75000

source_idsstring<uuid>[]

Sources owned by your organization. Generation waits for processing Sources; missing or failed Sources are rejected.

max items 100

speaker_charactersobject[]

Optional explicit assignments for a finished script: label as written in [brackets], and character_id from list_characters. Assignments override name matching; unmapped labels still match saved Character names.

min items 1 · max items 200

Show properties

Array of object

character_idstringrequired

min length 1

labelstringrequired

min length 1 · max length 200

style_idstring

Visual style ID. Omit to use the product's default style.

Allowed:almanacatomic-ageblueprintchalkboardclaymationcode-rushcrayondocumentarycinematicarchivalflatgouachepaper-machepixel-artretro-comicssketchstickmantier-listtoy-brickswatercolorwhiteboard-explainer

background_musicboolean

Include background music. Applies to Shorts, under three minutes, and defaults to on.

host_idsstring[]

Ordered Host IDs. Supports up to four. Do not combine with host_id.

min items 1 · max items 4

target_duration_secondsnumber

Target duration in seconds; the finished runtime can differ. 30 or 60 seconds makes a Short; 180 or more makes a Video. Without one, a script is measured by its narration and a prompt defaults to 300, or the longest length the plan allows under it.

Show properties

Any of:

number

number

number

number

number

number

number

number

number

number

number

number

number

number

number

number

number

number

Responses

202

Generation accepted. Check the status URL until generation finishes.

dataobjectrequired

Show properties

background_musicbooleanrequired

created_atstringrequired

errorstring | nullrequired

generation_idstring | nullrequired

host_idstring | nullrequired

host_idsstring[] | nullrequired

idstring<uuid>required

languagestringrequired

objectstringrequired

Allowed:shortvideo

orientationstringrequired

Allowed:LANDSCAPEPORTRAITSQUARE

phasestring | nullrequired

statusstringrequired

Allowed:idlegeneratingcompletedfailed

studio_urlstring<uri>required

style_idstringrequired

target_duration_secondsnumber | nullrequired

Requested target length in seconds, a generation input. The finished runtime can differ.

titlestringrequired

updated_atstringrequired

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

422

A finished script names speaker labels with no active saved Character. reason is unresolved_speakers and speakers lists each label; assign them with speaker_characters or create the Characters, then retry.

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

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

idempotency-keyheaderOptional 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.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.jellypod.com/v1/videos' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "host_id": "string",
  "language": "en",
  "orientation": "AUTO",
  "prompt": "string",
  "script": "string",
  "source_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "speaker_characters": [
    {
      "character_id": "string",
      "label": "string"
    }
  ],
  "style_id": "almanac",
  "background_music": true,
  "host_ids": [
    "string"
  ],
  "target_duration_seconds": 30
}'

const response = await fetch("https://api.jellypod.com/v1/videos", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"host_id\": \"string\",\n  \"language\": \"en\",\n  \"orientation\": \"AUTO\",\n  \"prompt\": \"string\",\n  \"script\": \"string\",\n  \"source_ids\": [\n    \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n  ],\n  \"speaker_characters\": [\n    {\n      \"character_id\": \"string\",\n      \"label\": \"string\"\n    }\n  ],\n  \"style_id\": \"almanac\",\n  \"background_music\": true,\n  \"host_ids\": [\n    \"string\"\n  ],\n  \"target_duration_seconds\": 30\n}"
});

import requests

response = requests.post(
    "https://api.jellypod.com/v1/videos",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"host_id\": \"string\",\n  \"language\": \"en\",\n  \"orientation\": \"AUTO\",\n  \"prompt\": \"string\",\n  \"script\": \"string\",\n  \"source_ids\": [\n    \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n  ],\n  \"speaker_characters\": [\n    {\n      \"character_id\": \"string\",\n      \"label\": \"string\"\n    }\n  ],\n  \"style_id\": \"almanac\",\n  \"background_music\": true,\n  \"host_ids\": [\n    \"string\"\n  ],\n  \"target_duration_seconds\": 30\n}",
)

Response

{
  "data": {
    "background_music": true,
    "created_at": "string",
    "error": "string",
    "generation_id": "string",
    "host_id": "string",
    "host_ids": [
      "string"
    ],
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "language": "en",
    "object": "short",
    "orientation": "LANDSCAPE",
    "phase": "string",
    "status": "idle",
    "studio_url": "http://example.com",
    "style_id": "string",
    "target_duration_seconds": 0,
    "title": "string",
    "updated_at": "string"
  }
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}

{
  "detail": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "reason": "unresolved_speakers",
  "recovery": {
    "action": "correct_input",
    "idempotency_key": "reuse",
    "poll_after_seconds": 0,
    "tool": "list_characters"
  },
  "request_id": "string",
  "speakers": [
    "string"
  ],
  "status": 0,
  "title": "string",
  "type": "bad_request"
}