> For the complete documentation index, see [llms.txt](https://shortgenius.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shortgenius.gitbook.io/api/guides/video-generation.md).

# Video Generation

ShortGenius excels at transforming a simple prompt, URL, or script into a fully produced video complete with AI-generated narration and images. This section outlines the step-by-step process to create, list, and retrieve videos.

## Drafting Videos

Before creating a final video, you'll typically **draft** one or more scripts. These drafts return structured "scenes" that you can review or modify.

### 1. Draft a Video

**Endpoint**: `POST /videos/drafts`

Use this when you want to generate a video script from a single **topic**. For example:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { ShortGenius } from 'shortgenius'

const client = new ShortGenius({
  bearerAuth: 'YOUR_API_TOKEN'
})

const draft = await client.draftVideo({
  topic: 'Benefits of Drinking Water',
  duration: '120',
  locale: 'en-US'
})

console.log(draft)
```

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

# Generate video topics first
topics = client.videos.generate_topics(
    parent_topic="health and wellness",
    locale="en-US",
    number_of_topics=3
)

# Use the first topic for our example
topic = topics[0] if topics else "Benefits of Drinking Water"

print(draft)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/drafts" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "topic": "Benefits of Drinking Water",
    "duration": "120",
    "locale": "en-US"
  }'
```

{% endtab %}
{% endtabs %}

**Request Body Fields**:

| Field      | Type   | Required | Description                                                                                                    |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| `topic`    | string | Yes      | The topic you want to generate a script about.                                                                 |
| `duration` | string | Yes      | Desired duration in **seconds** (e.g., "60", "120"). This is best-effort only; verify you have enough credits. |
| `locale`   | string | No       | Language locale (default `"auto"`).                                                                            |

**Sample Response**:

```json
{
  "title": "Top Reasons to Drink More Water",
  "caption": "Stay hydrated daily for better health and energy.",
  "scenes": [
    {
      "title": null,
      "caption": "Did you know that most people are chronically dehydrated?",
      "first_image_description": "A glass of water with ice cubes",
      "second_image_description": "A person feeling tired from dehydration"
    },
    ...
  ]
}
```

### 2. Draft a Video from a URL

**Endpoint**: `POST /videos/drafts/url`

Use this to fetch textual content from a given **webpage** and transform it into a video script.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const draft = await client.draftVideoFromURL({
  url: 'https://en.wikipedia.org/wiki/Water',
  prompt: 'Focus on health benefits only',
  locale: 'en-US'
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Note: URL-based drafting may not be available in current SDK version
# Generate topics as alternative approach
topics = client.videos.generate_topics(
    parent_topic="water benefits",
    locale="en-US",
    number_of_topics=1
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/drafts/url" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://en.wikipedia.org/wiki/Water",
    "prompt": "Focus on health benefits only",
    "locale": "en-US"
  }'
```

{% endtab %}
{% endtabs %}

### 3. Draft a Video from an Existing Script

**Endpoint**: `POST /videos/drafts/script`

If you already have a script written, ShortGenius can split it into logical scenes:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const draft = await client.draftVideoFromScript({
  script: 'Water is essential for all living organisms...',
  locale: 'en-US'
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Note: Script-based drafting may not be available in current SDK version
# Use topic generation instead
topics = client.videos.generate_topics(
    parent_topic="water science",
    locale="en-US",
    number_of_topics=1
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/drafts/script" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "script": "Water is essential for all living organisms...",
    "locale": "en-US"
  }'
```

{% endtab %}
{% endtabs %}

### 4. Draft a Quiz Video

**Endpoint**: `POST /videos/drafts/quiz`

Easily generate quiz-style content, complete with questions, multiple-choice answers, and a results explanation at the end.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const quiz = await client.draftQuizVideo({
  topic: 'Hydration Facts',
  locale: 'en-US'
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Note: Quiz drafting may not be available in current SDK version
# Use topic generation for quiz-style content
topics = client.videos.generate_topics(
    parent_topic="hydration quiz facts",
    locale="en-US",
    number_of_topics=1
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/drafts/quiz" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "topic": "Hydration Facts",
    "locale": "en-US"
  }'
```

{% endtab %}
{% endtabs %}

### 5. Draft a News Video

**Endpoint**: `POST /videos/drafts/news`

ShortGenius can gather recent headlines and generate a short news-style video for a given topic.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const news = await client.draftNewsVideo({
  topic: 'Latest Tech News',
  locale: 'en-US'
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Note: News drafting may not be available in current SDK version
# Use topic generation for news-style content
topics = client.videos.generate_topics(
    parent_topic="technology news",
    locale="en-US",
    number_of_topics=1
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/drafts/news" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "topic": "Latest Tech News",
    "locale": "en-US"
  }'
```

{% endtab %}
{% endtabs %}

***

## Creating the Final Video

Once you have a **draft** object (containing scenes or quiz data), you can pass it to the `/videos` endpoint to produce the final video file.

**Endpoint**: `POST /videos`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Get required resources
const connections = await client.getConnections()
const voices = await client.getVoices({ locale: 'en-US' })
const genres = await client.getMusicGenres()
const tracks = await client.getMusic(genres[0].name)

// Create the video
const video = await client.createVideo({
  contentType: 'Custom',
  locale: 'en-US',
  connectionIds: [connections[0].id],
  aspectRatio: '9:16',
  voicePlaybackRate: 100,
  voiceVolume: 100,
  soundtrackPlaybackRate: 100,
  soundtrackVolume: 100,
  title: 'All About Water',
  caption: 'Learn fun facts about water consumption!',
  scenes: draft.scenes, // Use scenes from your draft
  voiceId: voices[0].id,
  soundtrackId: tracks[0].id,
  publishAt: '2025-05-01T10:00:00Z'
})

console.log(`Video created: ${video.id}`)
```

{% endtab %}

{% tab title="Python" %}

```python
# Get required resources
connections = client.connections.list()
voices = client.audio.voices.list_voices(locale="en-US")

# Generate a topic first
topics = client.videos.generate_topics(
    parent_topic="water health benefits",
    locale="en-US",
    number_of_topics=1
)

# Create the video using a topic
video = client.videos.create(
    topic=topics[0] if topics else "Benefits of Drinking Water",
    locale="en-US",
    connection_ids=[connections[0].id],
    aspect_ratio="9:16",
    voice_id=voices[0].id if voices else None
)

print(f"Video created: {video.id}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "content_type": "Custom",
    "locale": "en-US",
    "connection_ids": ["<CONNECTION-ID>"],
    "aspect_ratio": "9:16",
    "voice_playback_rate": 100,
    "voice_volume": 100,
    "soundtrack_playback_rate": 100,
    "soundtrack_volume": 100,
    "title": "All About Water",
    "caption": "Learn fun facts about water consumption!",
    "scenes": [
      {
        "title": null,
        "caption": "Most people need at least 2 liters a day.",
        "first_image_description": "Close-up shot of a water bottle",
        "second_image_description": "Animated water droplets"
      },
      ...
    ],
    "voice_id": "<VOICE-ID>",
    "soundtrack_id": "<MUSIC-ID>",
    "publish_at": "2025-05-01T10:00:00Z"
  }'
```

{% endtab %}
{% endtabs %}

**Key Fields**:

| Field            | Required                                              | Description                                                         |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| `content_type`   | No                                                    | `"Custom"`, `"News"`, `"Quiz"`, etc.                                |
| `locale`         | No                                                    | `"en-US"`, `"auto"`, etc.                                           |
| `connection_ids` | Yes                                                   | Array of **publishing connections** (get them from `/connections`). |
| `title`          | Yes                                                   | Title of the final video.                                           |
| `caption`        | Yes                                                   | Caption/description to be displayed or posted with the video.       |
| `scenes`         | <p>Conditional<br><em>(required if not quiz)</em></p> | The array of scenes from your draft.                                |
| `quiz`           | <p>Conditional<br><em>(required if quiz)</em></p>     | Quiz content for quiz videos.                                       |
| `voice_id`       | No                                                    | ID of the voice for narration (from `/audio/voices`).               |
| `soundtrack_id`  | No                                                    | ID of the chosen soundtrack (from `/music/genres/{id}`).            |
| `aspect_ratio`   | No                                                    | `"9:16"`, `"16:9"`, `"1:1"`, etc.                                   |
| `publish_at`     | No                                                    | ISO 8601 date to schedule the video's publication.                  |

**Sample Successful Response**:

```json
{
  "id": "98e19721-8b1e-45a8-abc2-555c7a6cd75d",
  "title": "All About Water",
  "caption": "Learn fun facts about water consumption!",
  "created_at": "2025-05-01T09:00:00Z",
  "updated_at": null,
  "series_id": null,
  "publishing_state": "processing",
  "publish_at": "2025-05-01T10:00:00Z"
}
```

The video generation process might take some time. You can check its status via the **GET** `/videos/{id}` endpoint.

***

## Listing & Retrieving Videos

### List Videos

**Endpoint**: `GET /videos`

| Query Param | Default | Description                            |
| ----------- | ------- | -------------------------------------- |
| `page`      | 0       | Results page number (zero-based index) |
| `limit`     | 20      | Items per page                         |

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const response = await client.getVideos({
  page: 0,
  limit: 10
})

console.log(`Found ${response.videos.length} videos`)
console.log(`Has more: ${response.hasMore}`)

for (const video of response.videos) {
  console.log(`- ${video.title} (${video.id})`)
}
```

{% endtab %}

{% tab title="Python" %}

```python
response = client.videos.list(page=0, limit=10)

print(f"Found {len(response.videos)} videos")
print(f"Has more: {response.has_more}")

for video in response.videos:
    print(f"- {video.title} ({video.id})")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/videos?page=0&limit=10" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

### Retrieve a Single Video

**Endpoint**: `GET /videos/{id}`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const video = await client.getVideo('98e19721-8b1e-45a8-abc2-555c7a6cd75d')

console.log(`Title: ${video.title}`)
console.log(`Status: ${video.publishingState}`)
console.log(`Created: ${video.createdAt}`)
```

{% endtab %}

{% tab title="Python" %}

```python
video = client.videos.retrieve("98e19721-8b1e-45a8-abc2-555c7a6cd75d")

print(f"Title: {video.title}")
print(f"Status: {video.publishing_state}")
print(f"Created: {video.created_at}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/videos/98e19721-8b1e-45a8-abc2-555c7a6cd75d" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

***

## Generating Bulk Video Topics

Need multiple ideas for upcoming videos? ShortGenius can generate about 50–100 unique topics in one go.

**Endpoint**: `POST /videos/topics`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const topics = await client.generateVideoTopics({
  parentTopic: 'Water Conservation',
  locale: 'en-US',
  numberOfTopics: 50,
  contentType: 'Custom'
})

console.log(`Generated ${topics.length} topics:`)
topics.slice(0, 5).forEach(topic => {
  console.log(`- ${topic}`)
})
```

{% endtab %}

{% tab title="Python" %}

```python
topics = client.videos.generate_topics(
    parent_topic="Water Conservation",
    locale="en-US",
    number_of_topics=50,
    content_type="Custom"
)

print(f"Generated {len(topics)} topics:")
for topic in topics[:5]:
    print(f"- {topic}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/videos/topics" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "parent_topic": "Water Conservation",
    "locale": "en-US",
    "number_of_topics": 50,
    "content_type": "Custom"
  }'
```

{% endtab %}
{% endtabs %}

***

## Series (Batch or Ongoing Video Production)

If you want to create a continuous series of videos that follow a schedule, you can use the **/series** endpoints.

### Create a Video Series

**Endpoint**: `POST /series`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const series = await client.createSeries({
  contentType: 'Custom',
  locale: 'en-US',
  connectionIds: [connections[0].id],
  aspectRatio: '9:16',
  topics: [{ topic: 'Tip 1: Reusable Water Bottles' }, { topic: 'Tip 2: Short Showers vs Baths' }],
  schedule: {
    timeZone: 'America/Denver',
    times: [
      { dayOfWeek: 1, timeOfDay: 900 },
      { dayOfWeek: 3, timeOfDay: 1300 }
    ]
  }
})

console.log(`Series created: ${series.id}`)
```

{% endtab %}

{% tab title="Python" %}

```python
series = client.series.create(
    content_type="Custom",
    locale="en-US",
    connection_ids=[connections[0].id],
    aspect_ratio="9:16",
    topics=[
        {"topic": "Tip 1: Reusable Water Bottles"},
        {"topic": "Tip 2: Short Showers vs Baths"}
    ],
    schedule={
        "timeZone": "America/Denver",
        "times": [
            {"dayOfWeek": 1, "timeOfDay": 900},
            {"dayOfWeek": 3, "timeOfDay": 1300}
        ]
    }
)

print(f"Series created: {series.id}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/series" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "content_type": "Custom",
    "locale": "en-US",
    "connection_ids": ["<CONNECTION-ID>"],
    "aspect_ratio": "9:16",
    "topics": [
      {"topic": "Tip 1: Reusable Water Bottles"},
      {"topic": "Tip 2: Short Showers vs Baths"}
    ],
    "schedule": {
      "timeZone": "America/Denver",
      "times": [
        { "dayOfWeek": 1, "timeOfDay": 900 },
        { "dayOfWeek": 3, "timeOfDay": 1300 }
      ]
    }
  }'
```

{% endtab %}
{% endtabs %}

**Key Fields**:

* `topics` – An array of topics for each episode
* `schedule` – The day/time you want new episodes published
  * `timeOfDay` uses 24-hour format but without a separator (e.g., `900` = 9:00, `1300` = 13:00)

**Sample Response**:

```json
{
  "id": "c9b59ab6-2f1e-4c98-a833-e47e368c9615",
  "created_at": "2025-05-10T09:00:00Z",
  "next_posting_at": "2025-05-15T15:00:00Z",
  "type": "Series",
  "schedule": {
    "time_zone": "America/Denver",
    "times": [
      {
        "day_of_week": 1,
        "time_of_day": 900
      },
      {
        "day_of_week": 3,
        "time_of_day": 1300
      }
    ]
  },
  ...
}
```

### List All Series

**Endpoint**: `GET /series`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const response = await client.getAllSeries({ page: 0, limit: 20 })

for (const series of response.series) {
  console.log(`- ${series.id}: Next posting at ${series.nextPostingAt}`)
}
```

{% endtab %}

{% tab title="Python" %}

```python
response = client.series.list(page=0, limit=20)

for series in response.series:
    print(f"- {series.id}: Next posting at {series.next_posting_at}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/series" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

### Retrieve a Single Series

**Endpoint**: `GET /series/{id}`

Returns data about the series plus the individual **episodes** (videos) associated with it.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const series = await client.getSeries('c9b59ab6-2f1e-4c98-a833-e47e368c9615')

console.log(`Series type: ${series.type}`)
console.log(`Episodes: ${series.episodes?.length || 0}`)
```

{% endtab %}

{% tab title="Python" %}

```python
series = client.series.retrieve("c9b59ab6-2f1e-4c98-a833-e47e368c9615")

print(f"Series type: {series.type}")
print(f"Episodes: {len(series.episodes) if series.episodes else 0}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/series/c9b59ab6-2f1e-4c98-a833-e47e368c9615" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

***

## Next Steps

You can now:

* Create video drafts from topics, scripts, or even news headlines.
* Finalize those drafts into fully rendered videos.
* Generate topics in bulk.
* Set up a video **series** with a publishing schedule.

Continue to the [Image Generation](/api/guides/video-generation.md) section to learn how to incorporate custom AI-generated images into your projects.