---
search:
  tags:
    - Shorts
    - POST
seo:
  description: >-
    Create a short. Reference for the POST /v1/shorts endpoint in the Jellypod
    API.
sidebar:
  label: Create a short
  badge: POST
title: Create a short
type: openapi-operation
---
`POST /v1/shorts`

**Request body** (`application/json`, required)

- `host_id` (string) — Narrator Host ID. Required unless host\_ids is given. Do not combine with host\_ids.
- `language` (string) — Narration language code. Defaults to en.
- `orientation` (string) — Output orientation. Omit for AUTO, which follows the product policy.
- `prompt` (string) — 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.
- `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<uuid>[]) — 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.
- `style_id` (string) — Visual style ID. Omit to use the product's default style.
- `background_music` (boolean) — Include background music. Applies to Shorts, under three minutes, and defaults to on.
- `host_ids` (string[]) — Ordered Host IDs. Supports up to four. Do not combine with host\_id.
- `target_duration_seconds` (number) — 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 30, or the longest length the plan allows under it.

Request body example:

```json
{
  "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
}
```

**Responses**

- `202` — Generation accepted. Check the status URL until generation finishes.
- `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. Wait \`Retry-After\` seconds before retrying; \`RateLimit-Limit\`, \`RateLimit-Remaining\`, and \`RateLimit-Reset\` describe the window.
- `500` — Internal server error.

Response example, 202:

```json
{
  "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"
  }
}
```