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

# Get Templates

> Retrieve a list of all available video templates for styling and effects

# Get Templates

Retrieve a list of all available video templates that can be applied to your projects. Templates define the visual styling, animations, and effects that will be applied to your captions and video content.

<Note>
  This endpoint requires authentication and has a rate limit of 1000 requests per
  hour.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Submagic API key starting with `sk-`
</ParamField>

## Response

<ResponseField name="templates" type="array">
  Array of available template names that can be used in project creation
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.submagic.co/v1/templates" \
    -H "x-api-key: sk-your-api-key-here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.submagic.co/v1/templates", {
    headers: {
      "x-api-key": "sk-your-api-key-here",
    },
  });

  const data = await response.json();
  console.log(data.templates);
  ```

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

  headers = {
      'x-api-key': 'sk-your-api-key-here'
  }

  response = requests.get('https://api.submagic.co/v1/templates', headers=headers)
  data = response.json()

  print("Available templates:", data['templates'])
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
      "templates": [
          "Matt",
          "Jess",
          "Jack",
          "Nick",
          "Laura",
          "Kelly 2",
          "Caleb",
          "Kendrick",
          "Lewis",
          "Doug",
          "Carlos",
          "Luke",
          "Leila",
          "Mark",
          "Sara",
          "Daniel",
          "Dan 2",
          "Hormozi 4",
          "Dan",
          "Devin",
          "Tayo",
          "Ella",
          "Tracy",
          "Hormozi 1",
          "Hormozi 2",
          "Hormozi 3",
          "Hormozi 5",
          "Jason",
          "William",
          "Leon",
          "Ali",
          "Beast",
          "Maya",
          "Karl",
          "Iman",
          "Umi",
          "David",
          "Noah",
          "Gstaad",
          "Malta",
          "Nema",
          "seth"
      ]
  }
  ```
</ResponseExample>

## Using Templates

When creating a project, specify the template name in your request:

<CodeGroup>
  ```json URL-based Project theme={null}
  {
    "title": "My Trendy Video",
    "language": "en",
    "videoUrl": "https://example.com/video.mp4",
    "templateName": "Hormozi 2"
  }
  ```

  ```json File Upload Project theme={null}
  {
    "title": "Professional Presentation",
    "language": "en",
    "templateName": "Hormozi 2",
    "file": "video.mp4"
  }
  ```
</CodeGroup>

## Template Features

Each template includes:

* **Caption Styling**: Font family, size, color, and positioning
* **Animation Effects**: How captions appear and disappear
* **Visual Elements**: Background shapes, highlights, and decorative elements
* **Color Schemes**: Coordinated color palettes optimized for the template theme
* **Emoji Integration**: How emojis are displayed and animated
* **Layout Options**: Caption positioning and text alignment

## Template Preview

<Tip>
  While the API doesn't provide template previews directly, you can create small
  test projects with different templates to see how they look with your content
  style.
</Tip>

### Template Testing Strategy

```javascript theme={null}
const testTemplates = async (videoUrl, templates) => {
  const results = [];

  for (const template of templates.slice(0, 3)) {
    // Test first 3 templates
    try {
      const response = await fetch("https://api.submagic.co/v1/projects", {
        method: "POST",
        headers: {
          "x-api-key": process.env.SUBMAGIC_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          title: `Test - ${template}`,
          language: "en",
          videoUrl: videoUrl,
          templateName: template,
        }),
      });

      const project = await response.json();
      results.push({ template, projectId: project.id });

      // Wait between requests to respect rate limits
      await new Promise((resolve) => setTimeout(resolve, 2000));
    } catch (error) {
      console.error(`Failed to test template ${template}:`, error);
    }
  }

  return results;
};
```

## Best Practices

### Caching Templates

Since templates don't change frequently, cache the list:

```javascript theme={null}
class TemplateCache {
  constructor() {
    this.templates = null;
    this.lastFetch = null;
    this.cacheFor = 6 * 60 * 60 * 1000; // 6 hours
  }

  async getTemplates() {
    if (
      this.templates &&
      this.lastFetch &&
      Date.now() - this.lastFetch < this.cacheFor
    ) {
      return this.templates;
    }

    const response = await fetch("https://api.submagic.co/v1/templates", {
      headers: { "x-api-key": process.env.SUBMAGIC_API_KEY },
    });

    const data = await response.json();
    this.templates = data.templates;
    this.lastFetch = Date.now();

    return this.templates;
  }
}
```

## Error Responses

<ResponseField name="401 Unauthorized" type="object">
  ```json theme={null}
  {
    "error": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseField>

<ResponseField name="429 Rate Limited" type="object">
  ```json theme={null}
  {
    "error": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 30
  }
  ```
</ResponseField>

<ResponseField name="500 Server Error" type="object">
  ```json theme={null}
  {
    "error": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred"
  }
  ```
</ResponseField>

## Default Template

<Info>
  If you don't specify a `templateName` when creating a project, the system will
  automatically apply the "Sara" template, which is optimized for general
  social media content.
</Info>

<Warning>
  Template names are case-sensitive. Make sure to use the exact template name as
  returned by this endpoint.
</Warning>

{" "}