# Guides & Tutorials

Below are some practical examples showcasing how ShortGenius’s endpoints can be combined to build powerful AI-driven workflows. Each guide walks you through a common use case step by step.

***

## 1. Creating a Quiz Video from an Existing Script

**Use Case**: You have a short script or educational text and want to turn it into an interactive quiz video.

{% stepper %}
{% step %}
**Step 1: Prepare Your Script**

You have a script that looks like this (simplified):

```
"Water is essential for all living organisms. Humans should drink about 2 liters a day..."
```
{% endstep %}

{% step %}
**Step 2: Convert into Scenes (Optional)**

You can first test how the script would be split into scenes by using **POST** `/videos/drafts/script`. While not strictly necessary for a quiz, it’s helpful to see a standard draft.

```bash
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. Humans should drink about 2 liters a day..."
  }'
```
{% endstep %}

{% step %}
**Step 3: Draft a Quiz Video**

Now, use **POST** `/videos/drafts/quiz` to create a quiz:

```bash
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 Best Practices",
    "locale": "en-US"
  }'
```

This returns quiz-specific data:

```json
{
  "title": "Test Your Water Knowledge",
  "caption": "Are you a water expert?",
  "quiz": {
    "questions": [...],
    "results": {...}
  }
}
```
{% endstep %}

{% step %}
**Step 4: Create the Final Quiz Video**

When you’re satisfied with the quiz questions, pass them to **POST** `/videos`:

```bash
curl --request POST \
  --url "https://shortgenius.com/api/v1/videos" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "content_type": "Quiz",
    "locale": "en-US",
    "connection_ids": ["<CONNECTION-ID>"],
    "aspect_ratio": "9:16",
    "title": "Test Your Water Knowledge",
    "caption": "Are you a water expert?",
    "quiz": {
      "questions": [...],
      "results": {...}
    }
  }'
```

ShortGenius will generate an interactive quiz video, ready to share or schedule.
{% endstep %}
{% endstepper %}

***

## 2. Summarizing News

**Use Case**: You want an AI-generated video summarizing current events on a particular topic.

{% stepper %}
{% step %}
**Step 1: Draft a News Video**

Use **POST** `/videos/drafts/news` to fetch recent headlines and create scenes:

```bash
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"
  }'
```
{% endstep %}

{% step %}
**Step 2: Review Scenes**

Check the returned `scenes` array, which might have headlines and short text for each scene.\
If you see something you don’t like, you can edit the scene content, or omit certain headlines.
{% endstep %}

{% step %}
**Step 3: Finalize Video**

Send the edited `scenes` to **POST** `/videos`:

```bash
curl --request POST \
  --url "https://shortgenius.com/api/v1/videos" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "content_type": "News",
    "locale": "en-US",
    "connection_ids": ["<CONNECTION-ID>"],
    "title": "Weekly Tech Recap",
    "caption": "Your quick update on the latest in technology",
    "scenes": [
      {
        "title": "Apple Releases New Device",
        "caption": "Apple announces new product line..."
      },
      ...
    ]
  }'
```

ShortGenius will generate and (optionally) publish your **tech news** video.
{% endstep %}
{% endstepper %}

***

## 3. Bulk Video Creation

**Use Case**: You need to generate multiple videos (e.g., an educational series) with minimal manual effort.

{% stepper %}
{% step %}
**Step 1: Generate Video Topics**

Start by using **POST** `/videos/topics` to generate a list of potential video titles:

```bash
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": "Mental Health",
    "locale": "en-US",
    "number_of_topics": 10,
    "content_type": "Custom"
  }'
```

This returns about 10 related topics you can use.
{% endstep %}

{% step %}
**Step 2: Draft Each Topic**

Loop through each topic and **POST** `/videos/drafts` to create a draft script. Pseudocode:

```javascript
const topics = [
  /* from the /videos/topics response */
]
for (const t of topics) {
  const draft = await fetch('https://shortgenius.com/api/v1/videos/drafts', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      topic: t,
      duration: '90',
      locale: 'en-US'
    })
  })
  // handle the returned draft
}
```
{% endstep %}

{% step %}
**Step 3: Create Final Videos**

Once each draft is confirmed, send them to **POST** `/videos` with your connection IDs to automatically schedule.\
Optionally, store the video IDs for tracking or later reference.
{% endstep %}
{% endstepper %}

***

## 4. Creating AI Images & Adding Them to Video Scenes

**Use Case**: You want to create custom AI-generated images and place them into specific scenes for a more visually appealing video.

{% stepper %}
{% step %}
**Step 1: Generate an Image**

Use **POST** `/images`:

```bash
curl --request POST \
  --url "https://shortgenius.com/api/v1/images" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "A majestic snowy mountain under a sunrise",
    "aspect_ratio": "9:16",
    "wait_for_generation": true
  }'
```
{% endstep %}

{% step %}
**Step 2: Retrieve the Image ID**

In the response, you’ll see an `id` and (if ready) a `url`:

```json
{
  "id": "b2f08f0c-xxxx-xxxx-xxxx-ab8a88d12222",
  "url": "https://cdn.shortgenius.com/images/b2f08f0c.jpg",
  ...
}
```
{% endstep %}

{% step %}
**Step 3: Attach Image to a Video Scene**

When drafting a video or creating a final video, reference the newly generated image. Here’s an example:

```json
{
  "scenes": [
    {
      "title": "Mountain Scene",
      "caption": "This mountain stands tall at sunrise.",
      "first_image_id": "b2f08f0c-xxxx-xxxx-xxxx-ab8a88d12222",
      "second_image_description": "A hiker standing at the peak"
    }
  ]
}
```

Now your scene uses the custom AI image (`first_image_id`) and still generates a second image automatically.
{% endstep %}
{% endstepper %}

***

## Conclusion

These guides demonstrate how ShortGenius’s various endpoints work together to create dynamic, AI-driven content. Whether you’re making quiz-style videos, summarizing news, generating images, or scheduling a content series, ShortGenius has you covered.

**Happy Building!**
