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

**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.
- `captions_enabled` (boolean) — Show narration captions.
- `direction` (string) — Optional narration instructions for the uploaded visuals.
- `host_ids` (string[]) — Ordered Voiceover Host IDs. Supports up to four. Generation assigns each paragraph to one of them; reassign paragraphs in the editor. Do not combine with host\_id.
- `source_ids` (string<uuid>[], required) — Uploaded document or image Sources, in presentation order.
- `target_duration_seconds` (number) — Supported narration duration. Omit for automatic duration based on source content.
- `visual_motion` (string) — Zoom effect. Auto zooms image sources and holds document pages still, dynamic zooms every visual, static zooms none.

Request body example:

```json
{
  "host_id": "string",
  "language": "en",
  "orientation": "AUTO",
  "captions_enabled": false,
  "direction": "string",
  "host_ids": [
    "string"
  ],
  "source_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "target_duration_seconds": 180,
  "visual_motion": "auto"
}
```

**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.
- `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": "voiceover",
    "orientation": "LANDSCAPE",
    "phase": "string",
    "status": "idle",
    "studio_url": "http://example.com",
    "style_id": "string",
    "target_duration_seconds": 0,
    "title": "string",
    "updated_at": "string"
  }
}
```