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

# Get Smart Layouts

> Retrieve all smart layout templates available for video creation

## Overview

Fetch all smart layout templates available in your Pictory account. Smart layouts are pre-designed visual templates that define how text, visuals, and other elements are arranged in your video scenes. They provide professional styling with consistent positioning, animations, and visual effects.

Use this endpoint to retrieve available smart layouts for video creation, allowing users to select from pre-defined layout options that match their content style.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## What Are Smart Layouts?

Smart layouts are visual templates that control:

<CardGroup cols={2}>
  <Card title="Text Positioning" icon="text">
    Where subtitles and captions appear on screen
  </Card>

  <Card title="Visual Arrangement" icon="layer-group">
    How background media is displayed and cropped
  </Card>

  <Card title="Animations" icon="wand-magic-sparkles">
    Entry, exit, and emphasis animations for elements
  </Card>

  <Card title="Styling" icon="palette">
    Colors, fonts, and visual effects applied to scenes
  </Card>
</CardGroup>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/smartlayouts
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

Returns an object containing an array of smart layout templates.

<ResponseField name="items" type="array of objects">
  List of available smart layout templates

  <Expandable title="layout object">
    <ResponseField name="templateId" type="string" required>
      Unique identifier for the smart layout. Use this value for the `smartLayoutId` parameter when creating videos.
    </ResponseField>

    <ResponseField name="templateName" type="string" required>
      Descriptive name of the smart layout (e.g., "Modern minimalist", "Kinetic", "Chic")
    </ResponseField>

    <ResponseField name="schemaVersion" type="string" required>
      Version of the layout schema (e.g., "v3")
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "items": [
      {
        "templateId": "202507141030549677ylq8k8gu44vy1y",
        "templateName": "Modern minimalist",
        "schemaVersion": "v3"
      },
      {
        "templateId": "20250813042630669e658e159aa60455692c1dad5473adhg7",
        "templateName": "Kinetic",
        "schemaVersion": "v3"
      },
      {
        "templateId": "20250813042630669e658e159aa60455692c1dad5473adaa3",
        "templateName": "Chic",
        "schemaVersion": "v3"
      },
      {
        "templateId": "20250813042630669e658e159aa60455692c1dad5473adcf7",
        "templateName": "Wanderlust",
        "schemaVersion": "v3"
      },
      {
        "templateId": "20250813042630669e658e159aa60455692c1dad5473adtd3",
        "templateName": "Bulletin",
        "schemaVersion": "v3"
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

***

## Default Smart Layouts

The following smart layouts are available by default:

| Layout Name           | Style                                       | Best Used For                                            |
| --------------------- | ------------------------------------------- | -------------------------------------------------------- |
| **Modern minimalist** | Clean, simple design with subtle animations | Professional content, corporate videos, tutorials        |
| **Kinetic**           | Dynamic, energetic with bold movements      | Social media content, promotional videos, engaging clips |
| **Chic**              | Elegant, sophisticated styling              | Fashion, lifestyle, premium brand content                |
| **Wanderlust**        | Travel-inspired, adventurous feel           | Travel content, adventure videos, outdoor themes         |
| **Bulletin**          | News-style, informative layout              | News updates, announcements, educational content         |

<Tip>
  You can also create custom smart layouts in the Pictory App. Custom layouts will appear in your API response alongside the default layouts.
</Tip>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pictory.ai/pictoryapis/v1/smartlayouts' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

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

  url = "https://api.pictory.ai/pictoryapis/v1/smartlayouts"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  data = response.json()

  print(f"Total smart layouts available: {len(data['items'])}\n")

  # Display all layouts
  for layout in data['items']:
      print(f"- {layout['templateName']} (ID: {layout['templateId']})")
  ```

  ```javascript JavaScript / Node.js theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/smartlayouts',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const data = await response.json();

  console.log(`Total smart layouts available: ${data.items.length}\n`);

  // Display all layouts
  data.items.forEach(layout => {
    console.log(`- ${layout.templateName} (ID: ${layout.templateId})`);
  });
  ```

  ```php PHP theme={null}
  <?php
  function getSmartLayouts($apiKey) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/smartlayouts';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey,
          'accept: application/json'
      ]);

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 200) {
          throw new Exception('Request failed with status ' . $httpCode);
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $data = getSmartLayouts('YOUR_API_KEY');

      echo "Total smart layouts available: " . count($data['items']) . "\n\n";

      // Display all layouts
      foreach ($data['items'] as $layout) {
          echo "- {$layout['templateName']} (ID: {$layout['templateId']})\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```
</CodeGroup>

***

## Using Smart Layouts in Video Creation

Once you have the layout ID, use it with the `smartLayoutId` parameter when creating videos:

### Using Layout ID

```javascript theme={null}
const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard/render', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'my_video',
    smartLayoutId: '202507141030549677ylq8k8gu44vy1y', // Modern minimalist
    scenes: [{
      story: 'Your video content here',
      createSceneOnEndOfSentence: true
    }]
  })
});
```

### Using Layout Name

Alternatively, you can use the `smartLayoutName` parameter with the exact template name:

```javascript theme={null}
const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard/render', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'my_video',
    smartLayoutName: 'modern minimalist', // Case-insensitive
    scenes: [{
      story: 'Your video content here',
      createSceneOnEndOfSentence: true
    }]
  })
});
```

<Warning>
  You cannot use both `smartLayoutId` and `smartLayoutName` in the same request. Choose one method to specify your layout.
</Warning>

***

## Error Handling

<AccordionGroup>
  <Accordion title="401 - Unauthorized">
    ```json theme={null}
    {
      "message": "Unauthorized"
    }
    ```

    **Solution:** Check your API key is valid and correctly formatted in the Authorization header.
  </Accordion>

  <Accordion title="500 - Internal Server Error">
    ```json theme={null}
    {
      "error": {
        "code": "INTERNAL_ERROR",
        "message": "An unexpected error occurred"
      }
    }
    ```

    **Solution:** Retry the request. If the issue persists, contact support.
  </Accordion>
</AccordionGroup>

***

## Related APIs

<CardGroup cols={2}>
  <Card title="Create Storyboard Preview" icon="eye" href="/api-reference/videos/create-storyboard-preview">
    Use smart layouts when creating video previews
  </Card>

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

  <Card title="Get Text Styles" icon="font" href="/api-reference/branding/get-text-styles">
    Customize subtitle styling within layouts
  </Card>

  <Card title="Get Video Brands" icon="palette" href="/api-reference/branding/get-video-brands">
    Combine layouts with brand settings
  </Card>
</CardGroup>