# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shortgenius.gitbook.io/api/guides/video-generation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.