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:

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)

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)

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

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

Language locale (default "auto").

Sample Response:

{
  "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.

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

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

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

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:

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

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

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

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.

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

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

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

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.

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

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

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

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

// 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}`)

# 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}")

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

Key Fields:

Field

Required

Description

content_type

"Custom", "News", "Quiz", etc.

locale

"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

Conditional (required if not quiz)

The array of scenes from your draft.

quiz

Conditional (required if quiz)

Quiz content for quiz videos.

voice_id

ID of the voice for narration (from /audio/voices).

soundtrack_id

ID of the chosen soundtrack (from /music/genres/{id}).

aspect_ratio

"9:16", "16:9", "1:1", etc.

publish_at

ISO 8601 date to schedule the video's publication.

Sample Successful Response:

{
  "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

Endpoint: GET /videos

Query Param

Default

Description

page

Results page number (zero-based index)

limit

Items per page

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})`)
}

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})")

Retrieve a Single Video

Endpoint: GET /videos/{id}

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}`)

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

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}`)
})

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}")

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"
  }'

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

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}`)

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}")

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 }
      ]
    }
  }'

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:

{
  "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

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

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

Retrieve a Single Series

Endpoint: GET /series/{id}

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

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

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

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 section to learn how to incorporate custom AI-generated images into your projects.

PreviousAuthentication & Essentials NextVideo Series

Last updated 5 months ago

Drafting Videos

1. Draft a Video

2. Draft a Video from a URL

3. Draft a Video from an Existing Script

4. Draft a Quiz Video

5. Draft a News Video

Creating the Final Video

Listing & Retrieving Videos

List Videos

Retrieve a Single Video

Generating Bulk Video Topics

Series (Batch or Ongoing Video Production)

Create a Video Series

List All Series

Retrieve a Single Series

Next Steps