---
title: "Create a short"
method: POST
path: "/v1/shorts"
tags: ["Shorts"]
---

# Create a short

`POST /v1/shorts`

## Request

- Base URL: `https://api.jellypod.com`
- URL: `https://api.jellypod.com/v1/shorts`
- 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

- object
  - `host_id` string: Narrator Host ID. Required unless host_ids is given. Do not combine with host_ids.
  - `language` 'en' | 'es' | 'fr' | 'hi' | 'pt' | 'zh' | 'de' | 'ja' | 'ar' | 'ru' | 'ko' | 'id' | 'it' | 'nl' | 'tr' | 'pl' | 'sv' | 'fil' | 'ms' | 'ro' | 'uk' | 'el' | 'cs' | 'da' | 'fi' | 'no' | 'bg' | 'hr' | 'sk' | 'ta' | 'ace' | 'af' | 'ak' | 'sq' | 'am' | 'hy' | 'as' | 'awa' | 'az' | 'ban' | 'bjn' | 'ba' | 'eu' | 'be' | 'bem' | 'bn' | 'bho' | 'bs' | 'bug' | 'my' | 'yue' | 'ca' | 'ckb' | 'hne' | 'ny' | 'crh' | 'dyu' | 'dz' | 'et' | 'gl' | 'lg' | 'ka' | 'gn' | 'gu' | 'ht' | 'ha' | 'he' | 'hu' | 'is' | 'ig' | 'ga' | 'jv' | 'kab' | 'kam' | 'kn' | 'ks' | 'kk' | 'km' | 'ki' | 'rw' | 'kg' | 'ky' | 'lo' | 'ltg' | 'lv' | 'lt' | 'lb' | 'mk' | 'mag' | 'mai' | 'ml' | 'mt' | 'mni' | 'mr' | 'min' | 'lus' | 'mn' | 'ne' | 'nso' | 'or' | 'pag' | 'ps' | 'fa' | 'pa' | 'sat' | 'sr' | 'sd' | 'si' | 'sl' | 'so' | 'sw' | 'ss' | 'tg' | 'te' | 'th' | 'ti' | 'ur' | 'ug' | 'uz' | 'vi' | 'cy': Narration language code. Defaults to en.
  - `orientation` 'AUTO' | 'PORTRAIT' | 'LANDSCAPE' | 'SQUARE': Output orientation. Omit for AUTO, which follows the product policy.
  - `prompt` string: Instructions for writing new narration: describe the story, audience, and desired result. To preserve finished narration word for word, use script instead.
  - `script` string: 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.
  - `source_ids` string[]: Sources owned by your organization. Generation waits for processing Sources; missing or failed Sources are rejected.
  - `speaker_characters` object[]: 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.
    - `character_id` string, required
    - `label` string, required
  - `style_id` 'almanac' | 'atomic-age' | 'blueprint' | 'chalkboard' | 'claymation' | 'crayon' | 'flat' | 'gouache' | 'paper-mache' | 'pixel-art' | 'retro-comics' | 'sketch' | 'stickman' | 'toy-bricks' | 'watercolor' | 'whiteboard-explainer': Visual style ID. Omit to use the product's default style.
  - `background_music` boolean: Include background music. Defaults to on.
  - `host_ids` string[]: Ordered Short Host IDs. Supports up to four. Do not combine with host_id.
  - `target_duration_seconds` union: Short duration: 30 or 60 seconds.
    - 30
    - 60

## Response `202`

Generation accepted. Check the status URL until generation finishes.

- object
  - `data` object, required
    - `background_music` boolean, required
    - `created_at` string, required
    - `error` string, nullable, required
    - `generation_id` string, nullable, required
    - `host_id` string, nullable, required
    - `host_ids` string[], nullable, required
    - `id` string, uuid, required
    - `language` 'en' | 'es' | 'fr' | 'hi' | 'pt' | 'zh' | 'de' | 'ja' | 'ar' | 'ru' | 'ko' | 'id' | 'it' | 'nl' | 'tr' | 'pl' | 'sv' | 'fil' | 'ms' | 'ro' | 'uk' | 'el' | 'cs' | 'da' | 'fi' | 'no' | 'bg' | 'hr' | 'sk' | 'ta' | 'ace' | 'af' | 'ak' | 'sq' | 'am' | 'hy' | 'as' | 'awa' | 'az' | 'ban' | 'bjn' | 'ba' | 'eu' | 'be' | 'bem' | 'bn' | 'bho' | 'bs' | 'bug' | 'my' | 'yue' | 'ca' | 'ckb' | 'hne' | 'ny' | 'crh' | 'dyu' | 'dz' | 'et' | 'gl' | 'lg' | 'ka' | 'gn' | 'gu' | 'ht' | 'ha' | 'he' | 'hu' | 'is' | 'ig' | 'ga' | 'jv' | 'kab' | 'kam' | 'kn' | 'ks' | 'kk' | 'km' | 'ki' | 'rw' | 'kg' | 'ky' | 'lo' | 'ltg' | 'lv' | 'lt' | 'lb' | 'mk' | 'mag' | 'mai' | 'ml' | 'mt' | 'mni' | 'mr' | 'min' | 'lus' | 'mn' | 'ne' | 'nso' | 'or' | 'pag' | 'ps' | 'fa' | 'pa' | 'sat' | 'sr' | 'sd' | 'si' | 'sl' | 'so' | 'sw' | 'ss' | 'tg' | 'te' | 'th' | 'ti' | 'ur' | 'ug' | 'uz' | 'vi' | 'cy', required
    - `object` 'short', required
    - `orientation` 'LANDSCAPE' | 'PORTRAIT' | 'SQUARE', required
    - `phase` string, nullable, required
    - `status` 'idle' | 'generating' | 'completed' | 'failed', required
    - `studio_url` string, uri, required
    - `style_id` string, required
    - `target_duration_seconds` number, nullable, required
    - `title` string, required
    - `updated_at` 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.
- `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.
- `429`: Rate limit exceeded. Response includes `Retry-After`, `RateLimit`, and `RateLimit-Policy` headers (IETF draft).
- `500`: Internal server error.

---

[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)