> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Layouts for Videos

> Create professional videos with smart layouts using the Pictory API for enhanced visual presentation

This guide shows you how to create videos with smart layouts that enhance the visual presentation of your content. Smart layouts provide professionally designed templates that combine text, visuals, and animations for engaging video content.

<Frame>
  <img src="https://mintcdn.com/pictory/Ke4wsQHfnOm3AR96/images/smart_themes.png?fit=max&auto=format&n=Ke4wsQHfnOm3AR96&q=85&s=db66db239f768bac8a9b5dd06144b9ff" alt="Smart Layout Options" width="1922" height="1082" data-path="images/smart_themes.png" />
</Frame>

## What You'll Learn

<CardGroup cols={2}>
  <Card title="Smart Layouts" icon="table-layout">
    Apply professionally designed visual layouts
  </Card>

  <Card title="Layout Selection" icon="circle-check">
    Choose layouts by name or ID
  </Card>

  <Card title="Visual Styles" icon="palette">
    Create consistent, polished video aesthetics
  </Card>

  <Card title="Combined Features" icon="layer-group">
    Use layouts with voice-over and other features
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Text content ready for video conversion
* Understanding of which layout style fits your content

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## Available Smart Layouts

Pictory provides five distinct smart layout styles, each designed for different content types and visual aesthetics:

| Layout Name           | Style                                                 | Best Used For                                                     |
| --------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
| **Modern minimalist** | Clean, professional design with subtle animations     | Business presentations, corporate content, professional tutorials |
| **Kinetic**           | Dynamic, energetic layout with bold typography        | Marketing videos, product launches, social media ads              |
| **Chic**              | Elegant, sophisticated design with stylish elements   | Fashion, lifestyle content, premium brand videos                  |
| **Wanderlust**        | Travel-inspired layout with split-screen visuals      | Travel content, testimonials, storytelling videos                 |
| **Bulletin**          | News-style layout with structured information display | Educational content, news updates, informational videos           |

<Note>
  Smart layouts automatically handle text positioning, animations, and visual styling. When using smart layouts, the `maxSubtitleLines` parameter is not available at the scene level as the layout manages text display automatically.
</Note>

## How Smart Layouts Work

When you apply a smart layout to your video:

1. **Layout Selection** - You specify the layout by name or ID
2. **Text Processing** - Your story content is analyzed and formatted
3. **Visual Styling** - Layout-specific styling is applied to text and elements
4. **Animation Application** - Pre-designed animations enhance visual appeal
5. **Scene Composition** - Text, visuals, and backgrounds are combined
6. **Video Rendering** - Final video is assembled with the complete layout design

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  const SAMPLE_TEXT =
    "AI is poised to significantly impact educators and course creators on social media. " +
    "By automating tasks like content generation, visual design, and video editing, " +
    "AI will save time and enhance consistency.";

  async function createVideoWithSmartLayout() {
    try {
      console.log("Creating video with smart layout...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "text_to_video_smart_layout",

          // Smart layout configuration
          smartLayoutName: "modern minimalist",  // Choose your layout

          // Voice-over configuration
          voiceOver: {
            enabled: true,
            aiVoices: [
              {
                speaker: "Brian",              // AI voice name
                speed: 100,                    // Normal speed (50-200)
                amplificationLevel: 0,         // Normal volume (-1 to 1)
              },
            ],
          },

          // Scene configuration
          scenes: [
            {
              story: SAMPLE_TEXT,
              createSceneOnNewLine: true,
              createSceneOnEndOfSentence: true,
            },
          ],
        },
        {
          headers: {
            "Content-Type": "application/json",
            Authorization: API_KEY,
          },
        }
      );

      const jobId = response.data.data.jobId;
      console.log("✓ Video creation started!");
      console.log("Job ID:", jobId);

      // Monitor progress
      console.log("\nMonitoring video creation...");
      let jobCompleted = false;
      let jobResult = null;

      while (!jobCompleted) {
        const statusResponse = await axios.get(
          `${API_BASE_URL}/v1/jobs/${jobId}`,
          {
            headers: { Authorization: API_KEY },
          }
        );

        const status = statusResponse.data.data.status;
        console.log("Status:", status);

        if (status === "completed") {
          jobCompleted = true;
          jobResult = statusResponse.data;
          console.log("\n✓ Video with smart layout is ready!");
          console.log("Video URL:", jobResult.data.videoURL);
        } else if (status === "failed") {
          throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
      }

      return jobResult;
    } catch (error) {
      console.error("Error:", error.response?.data || error.message);
      throw error;
    }
  }

  createVideoWithSmartLayout();
  ```

  ```python Python theme={null}
  import requests
  import time
  import json

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  SAMPLE_TEXT = (
      "AI is poised to significantly impact educators and course creators on social media. "
      "By automating tasks like content generation, visual design, and video editing, "
      "AI will save time and enhance consistency."
  )

  def create_video_with_smart_layout():
      try:
          print("Creating video with smart layout...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'text_to_video_smart_layout',

                  # Smart layout configuration
                  'smartLayoutName': 'modern minimalist',  # Choose your layout

                  # Voice-over configuration
                  'voiceOver': {
                      'enabled': True,
                      'aiVoices': [
                          {
                              'speaker': 'Brian',              # AI voice name
                              'speed': 100,                    # Normal speed (50-200)
                              'amplificationLevel': 0          # Normal volume (-1 to 1)
                          }
                      ]
                  },

                  # Scene configuration
                  'scenes': [
                      {
                          'story': SAMPLE_TEXT,
                          'createSceneOnNewLine': True,
                          'createSceneOnEndOfSentence': True
                      }
                  ]
              },
              headers={
                  'Content-Type': 'application/json',
                  'Authorization': API_KEY
              }
          )
          response.raise_for_status()

          job_id = response.json()['data']['jobId']
          print("✓ Video creation started!")
          print(f"Job ID: {job_id}")

          # Monitor progress
          print("\nMonitoring video creation...")
          job_completed = False
          job_result = None

          while not job_completed:
              status_response = requests.get(
                  f'{API_BASE_URL}/v1/jobs/{job_id}',
                  headers={'Authorization': API_KEY}
              )
              status_response.raise_for_status()

              status = status_response.json()['data']['status']
              print(f"Status: {status}")

              if status == 'completed':
                  job_completed = True
                  job_result = status_response.json()
                  print("\n✓ Video with smart layout is ready!")
                  print(f"Video URL: {job_result['data']['videoURL']}")
              elif status == 'failed':
                  raise Exception(f"Video creation failed: {status_response.json()}")

              time.sleep(5)

          return job_result

      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")
          if hasattr(error, 'response') and error.response is not None:
              print(f"Response: {error.response.text}")
          raise

  if __name__ == '__main__':
      create_video_with_smart_layout()
  ```
</CodeGroup>

## Understanding the Parameters

### Smart Layout Configuration

| Parameter         | Type   | Required | Description                                                    |
| ----------------- | ------ | -------- | -------------------------------------------------------------- |
| `smartLayoutName` | string | No       | Name of the smart layout (use this OR smartLayoutId, not both) |
| `smartLayoutId`   | string | No       | ID of the smart layout (use this OR smartLayoutName, not both) |

### Valid Smart Layout Names

| Value               | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `modern minimalist` | Clean, professional design with subtle animations     |
| `kinetic`           | Dynamic, energetic layout with bold typography        |
| `chic`              | Elegant, sophisticated design with stylish elements   |
| `wanderlust`        | Travel-inspired layout with split-screen visuals      |
| `bulletin`          | News-style layout with structured information display |

<Warning>
  **Smart Layout Restrictions**

  When using smart layouts, the following restrictions apply:

  * `maxSubtitleLines` cannot be used at the scene level
  * The layout automatically manages text display and positioning
  * Use either `smartLayoutName` OR `smartLayoutId`, not both
</Warning>

## Layout Selection Methods

### Using Layout Name

The simplest way to select a smart layout is by name:

```javascript theme={null}
{
  smartLayoutName: "kinetic"
}
```

### Using Layout ID

For programmatic consistency, you can use the layout ID:

```javascript theme={null}
{
  smartLayoutId: "your-layout-id-here"
}
```

<Note>
  Layout IDs provide stability if layout names change in the future. Use the name for human-readable code and ID for automated systems.
</Note>

## Common Use Cases

### Corporate Presentation

```javascript theme={null}
{
  smartLayoutName: "modern minimalist",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Brian",
      speed: 95,
      amplificationLevel: 0
    }]
  },
  scenes: [{
    story: "Your quarterly results presentation content..."
  }]
}
```

**Result:** Professional, clean video perfect for business presentations.

### Marketing Campaign

```javascript theme={null}
{
  smartLayoutName: "kinetic",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Matthew",
      speed: 110,
      amplificationLevel: 0.2
    }]
  },
  scenes: [{
    story: "Introducing our latest product innovation..."
  }]
}
```

**Result:** Dynamic, energetic video for product launches and promotions.

### Fashion and Lifestyle

```javascript theme={null}
{
  smartLayoutName: "chic",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Emma",
      speed: 100,
      amplificationLevel: 0
    }]
  },
  scenes: [{
    story: "Discover the latest trends in sustainable fashion..."
  }]
}
```

**Result:** Elegant, sophisticated video for lifestyle and fashion brands.

### Travel Content

```javascript theme={null}
{
  smartLayoutName: "wanderlust",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Amy",
      speed: 100,
      amplificationLevel: 0
    }]
  },
  scenes: [{
    story: "Experience the breathtaking views of the Swiss Alps..."
  }]
}
```

**Result:** Immersive, travel-inspired video with testimonial-style presentation.

### Educational Content

```javascript theme={null}
{
  smartLayoutName: "bulletin",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Joanna",
      speed: 90,
      amplificationLevel: 0
    }]
  },
  scenes: [{
    story: "Today we'll explore the fundamentals of machine learning..."
  }]
}
```

**Result:** Structured, informational video perfect for tutorials and courses.

## Best Practices

<AccordionGroup>
  <Accordion title="Match Layout to Content Type">
    Choose the right layout for your content:

    * **Modern Minimalist:** Business reports, corporate updates, professional tutorials
    * **Kinetic:** Product launches, social media ads, energetic promotions
    * **Chic:** Fashion content, luxury brands, lifestyle videos
    * **Wanderlust:** Travel vlogs, testimonials, storytelling
    * **Bulletin:** Educational content, news updates, informational videos
  </Accordion>

  <Accordion title="Combine with Voice-Over">
    Smart layouts work best when paired with AI voice-over:

    * Voice narration enhances the visual storytelling
    * Text and voice complement each other
    * Creates more engaging, professional content
    * Voice speed should match the layout energy
  </Accordion>

  <Accordion title="Consider Your Audience">
    Select layouts based on viewer expectations:

    * **B2B Content:** Modern Minimalist, Bulletin
    * **Consumer Marketing:** Kinetic, Chic
    * **Social Media:** Kinetic, Wanderlust
    * **Educational:** Bulletin, Modern Minimalist
    * **Brand Storytelling:** Wanderlust, Chic
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Invalid smart layout name">
    **Problem:** API returns error about invalid layout name.

    **Solution:**

    * Check spelling and case sensitivity
    * Use exact names: "modern minimalist", "kinetic", "chic", "wanderlust", "bulletin"
    * Ensure you are not using both name and ID
    * Remove extra spaces or characters from the name
  </Accordion>

  <Accordion title="maxSubtitleLines error with smart layout">
    **Problem:** API returns error about maxSubtitleLines not being allowed.

    **Solution:**

    * Remove `maxSubtitleLines` from all scene configurations
    * Smart layouts automatically manage text display
    * The layout handles subtitle line formatting
    * Use scene breaks to control text pacing instead
  </Accordion>

  <Accordion title="Layout Does Not Match Expected Style">
    **Problem:** Video uses a different layout than expected.

    **Solution:**

    * Verify the layout name spelling is correct
    * Double-check you are not using both name and ID
    * Ensure the parameter is at the video level, not scene level
    * Review the available layout options in this guide
  </Accordion>
</AccordionGroup>

## Next Steps

Enhance your smart layout videos with these features:

<CardGroup cols={2}>
  <Card title="AI Voice-Over" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Add professional narration to complement layouts
  </Card>

  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add music to enhance the visual experience
  </Card>

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Apply consistent branding across videos
  </Card>

  <Card title="Logo Integration" icon="image" href="/guides/branding-customization/logo">
    Add your logo to branded content
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

<CardGroup cols={2}>
  <Card title="Get Smart Layouts" icon="table-layout" href="/api-reference/smartlayouts/get-smart-layouts">
    List all available smart layout templates
  </Card>

  <Card title="Render Storyboard Video" icon="video" href="/api-reference/videos/render-storyboard-video">
    Apply smart layouts to rendered videos
  </Card>

  <Card title="Create Storyboard Preview" icon="eye" href="/api-reference/videos/create-storyboard-preview">
    Preview videos with smart layouts
  </Card>

  <Card title="Get Storyboard Preview Job" icon="clock" href="/api-reference/jobs/get-storyboard-preview-job-by-id">
    Monitor storyboard creation progress
  </Card>
</CardGroup>