# Video Series

## 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
import { ShortGenius } from 'shortgenius'

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

const topics = await client.generateVideoTopics({
  parent_topic: 'Water Conservation',
  locale: 'en-US',
  number_of_topics: 50,
  content_type: 'Custom'
})

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

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

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://shortgenius.com/api/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 %}

**Sample Response**:

```json
[
  "Why Saving Water Matters",
  "Water Conservation Tips for Home",
  "Rainwater Harvesting Basics",
  ...
]
```

***

## 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 connections = await client.getConnections()

const series = await client.createSeries({
  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 }
    ]
  }
})

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

{% endtab %}

{% tab title="Python" %}

```python
connections = client.connections.list()

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}")
print(f"Next posting: {series.next_posting_at}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://shortgenius.com/api/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
})

console.log(`Found ${response.series.length} series`)
console.log(`Has more: ${response.has_more}`)

for (const series of response.series) {
  console.log(`- ${series.id}`)
  console.log(`  Type: ${series.type}`)
  console.log(`  Next posting: ${series.next_posting_at}`)
}
```

{% endtab %}

{% tab title="Python" %}

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

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

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

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://shortgenius.com/api/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 ID: ${series.id}`)
console.log(`Type: ${series.type}`)
console.log(`Created: ${series.created_at}`)

if (series.episodes) {
  console.log(`\nEpisodes (${series.episodes.length}):`)
  for (const episode of series.episodes) {
    console.log(`- ${episode.title} (${episode.id})`)
    console.log(`  Status: ${episode.publishing_state}`)
  }
}
```

{% endtab %}

{% tab title="Python" %}

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

print(f"Series ID: {series.id}")
print(f"Type: {series.type}")
print(f"Created: {series.created_at}")

if series.episodes:
    print(f"\nEpisodes ({len(series.episodes)}):")
    for episode in series.episodes:
        print(f"- {episode.title} ({episode.id})")
        print(f"  Status: {episode.publishing_state}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://shortgenius.com/api/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](https://shortgenius.gitbook.io/api/guides/video-generation) section to learn how to incorporate custom AI-generated images into your projects.