ShortGenius

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)

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:

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

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

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

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

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

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

Conditional (required if not quiz)

The array of scenes from your draft.

quiz

Conditional (required if quiz)

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:

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

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

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

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

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 & EssentialsNextVideo Series

Last updated