# 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://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 %}

**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://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
})

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://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 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://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-series.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.