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:

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)

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)

cURL

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

TypeScript

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

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
)

cURL

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:

TypeScript

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

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
)

cURL

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.

TypeScript

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

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
)

cURL

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.

TypeScript

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

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
)

cURL

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

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

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

cURL

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

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

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

cURL

curl --request GET \
  --url "https://shortgenius.com/api/v1/videos?page=0&limit=10" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Retrieve a Single Video

Endpoint: GET /videos/{id}

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

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

cURL

curl --request GET \
  --url "https://shortgenius.com/api/v1/videos/98e19721-8b1e-45a8-abc2-555c7a6cd75d" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

---

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

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

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

cURL

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

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

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

cURL

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

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

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

cURL

curl --request GET \
  --url "https://shortgenius.com/api/v1/series" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Retrieve a Single Series

Endpoint: GET /series/{id}

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

TypeScript

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

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

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

cURL

curl --request GET \
  --url "https://shortgenius.com/api/v1/series/c9b59ab6-2f1e-4c98-a833-e47e368c9615" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

---

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.