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:

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.

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:

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

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.

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.

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

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": "556",
    "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	"556", "969", "61", etc. (5:5.6, 9:16, or 6:1).
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

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

Sample Response:

{
  "videos": [
    {
      "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"
    },
    ...
  ],
  "has_more": false
}

Retrieve a Single Video

Endpoint: GET /videos/{id}

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

Sample 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": "2025-05-01T10:02:00Z",
  "series_id": null,
  "publishing_state": "completed",
  "publish_at": "2025-05-01T10:00:00Z"
}

---

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

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

Sample Response:

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

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": "556",
    "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

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.

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.