Skip to main content
GET
/
v1
/
templates
curl -X GET "https://api.submagic.co/v1/templates" \
  -H "x-api-key: sk-your-api-key-here"

{
    "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"
    ]
}

​
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.
This endpoint requires authentication and has a rate limit of 1000 requests per hour.

​
Authentication

​
x-api-key
string
required
Your Submagic API key starting with sk-

​
Response

​
templates
array
Array of available template names that can be used in project creation
curl -X GET "https://api.submagic.co/v1/templates" \
  -H "x-api-key: sk-your-api-key-here"

{
    "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"
    ]
}

​
Using Templates

When creating a project, specify the template name in your request: 
{
  "title": "My Trendy Video",
  "language": "en",
  "videoUrl": "https://example.com/video.mp4",
  "templateName": "Hormozi 2"
}

​
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

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.

​
Template Testing Strategy

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: 
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

​
401 Unauthorized
object
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
​
429 Rate Limited
object
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}
​
500 Server Error
object
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}

​
Default Template

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.
Template names are case-sensitive. Make sure to use the exact template name as returned by this endpoint.