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

# Overview

> Learn how to use the Creatify.ai Custom Templates API to generate videos using custom templates and data.

## Introduction

The Custom Templates API allows you to generate videos from custom templates and data using the Creatify.ai platform. This guide will walk you through the process of creating a video using the API.

<video controls className="w-full aspect-video" src="https://d35ghwdno3nak3.cloudfront.net/creatify-made-videos/Custom-template-API-introduction.mp4" />

## Quickstart

### Prerequisite

* You need a creatify.ai account with API access.
* You need to go through the [Get your API key](/api-reference/authentication) to obtain your API credentials (X-API-ID and X-API-KEY).

### Creating Custom Templates via the **Creatify.ai** Website

Creating custom templates on the **Creatify.ai** website is a straightforward process that allows you to leverage dynamic content through API integration. Follow these steps to create and configure your custom templates:

***

#### Step 1: Access the Editor

Visit the **Creatify.ai** website and log into your account. Navigate to **Projects** in the dashboard, find a project, and click to **edit** it.

***

#### Step 2: Add API Variables

While editing your project on the **Creatify.ai** website, click on any of the following elements to add API variables. This action transforms your project into a **custom template**:

##### Avatar

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-avatar.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=ad01b70fb5e853a5d46c5759c04b5c14" alt="Add Avatar Element on Creatify.ai" width="2876" height="1882" data-path="images/custom-template-avatar.png" />\
On **Creatify.ai**, use avatar API variable to dynamically change the avatar\_id in your video.
`avatar_id` is the unique identifier of an avatar. You can get the `avatar_id` by calling the [Get avatar](/api-reference/personas/get-apipersonas) endpoint.

##### Image

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-image.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=beee33bdb52a1bd638590e1a5a1bef90" alt="Add Image Element on Creatify.ai" width="2904" height="1808" data-path="images/custom-template-image.png" />\
On **Creatify.ai**, use avatar image API variable to dynamically change the image in your video.

##### Video

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-video.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=6f1e59329e60218a7b39d21531862438" alt="Add Video Element on Creatify.ai" width="2908" height="1796" data-path="images/custom-template-video.png" />\
On **Creatify.ai**, use avatar video API variable to dynamically change the video clip in your video.

##### Audio

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-audio.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=cc32ad2623a1889fae17e7b3f5032de7" alt="Add Audio Element on Creatify.ai" width="2916" height="1888" data-path="images/custom-template-audio.png" />\
On **Creatify.ai**, use audio API variable to dynamically change background music in your video.

##### Text (Overlay Text or Scene Text)

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-scene-tex.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=1808fc030dae014307dfd3d47f4170ff" alt="Add Text Element (Scene Text) on Creatify.ai" width="2894" height="1794" data-path="images/custom-template-scene-tex.png" />\
<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-overlay-text.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=5db4e1f1dc63127894486225d26563c0" alt="Add Text Element (Overlay Text) on Creatify.ai" width="2896" height="1828" data-path="images/custom-template-overlay-text.png" />\
On **Creatify.ai**, for **text** elements (including overlay text or scene text), use the `{{variable_name}}` syntax to specify variable content replacement. The default content will be an empty string.

Example: Text Content Replacement

If your project contains a text element with the content: `Welcome to {{company_name}}!`
When generating the video, you can pass the variable in the API request as follows:

```json theme={null}
{
  "variables": {
    "company_name": {
      "type": "text",
      "properties": {
        "content": "Creatify Inc."
      }
    }
  }
}
```

The resulting text in the video will be: `Welcome to Creatify Inc.!`

If `company_name` variable is not provided in the variables, the resulting text in the video will be: `Welcome to !`

##### Voiceover

<img src="https://mintcdn.com/creatify/fobKWPKCdJDOWjln/images/custom-template-voiceover.png?fit=max&auto=format&n=fobKWPKCdJDOWjln&q=85&s=9b59a7f34bb7e5a349d3c19350fe8e48" alt="Add Voiceover Element on Creatify.ai" width="2886" height="1882" data-path="images/custom-template-voiceover.png" />\
On **Creatify.ai**, use voiceover API variable to dynamically change the voice\_id in your video.
`voice_id` is the unique identifier of the voice. You can get the voice\_id by calling the [Get voices](/api-reference/voices/get-apivoices) interface.

***

#### Step 3: Get the Custom Template ID

Once your custom template is configured and saved on the **Creatify.ai** website, locate the **template ID**. This ID corresponds to the **video ID** displayed in the browser's URL. Use this ID when making API calls to generate videos based on your custom template.

***

#### Example Usage

In the example images above, clicking on an avatar, image, video, audio, text, or voiceover element on the Creatify.ai website allows you to add API variables. These variables transform the project into a custom template, ready for integration via the Creatify.ai API.

### Listing Custom Templates

Retrieve the list of available custom templates:

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.creatify.ai/api/custom_templates/'
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: you-api-key'
  ```

  ```json Response theme={null}
  [
    {
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8",
      "name": null,
      "preview": "https://app.creatify.ai/preview?layout=videos/20250519/ed39a2ed-90aa-4e06-adeb-1f5513a1dae1.json",
      "aspect_ratio": "9x16",
      "created_at": "2025-05-19T12:10:08.352977-07:00",
      "updated_at": "2025-05-19T12:15:36.329684-07:00
    }
  ]
  ```
</CodeGroup>

### Get Custom Template Details

Retrieve the details of a specific custom template by its ID:

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.creatify.ai/api/custom_templates/f74f67a5-5008-46c9-b4a9-d5aebff142a8/'
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: you-api-key'
  ```

  ```json Response [expandable] theme={null}
  {
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8",
      "name": null,
      "preview": "https://app.creatify.ai/preview?layout=videos/20250519/ed39a2ed-90aa-4e06-adeb-1f5513a1dae1.json",
      "aspect_ratio": "9x16",
      "created_at": "2025-05-19T12:10:08.352977-07:00",
      "updated_at": "2025-05-19T12:15:36.329684-07:00",
      "variables": {
          "video": {
              "type": "video"
          },
          "scene_text": {
              "type": "text"
          },
          "voiceover": {
              "type": "voiceover"
          },
          "image": {
              "type": "image"
          },
          "TEXT": {
              "type": "text"
          },
          "audio": {
              "type": "audio"
          },
          "avatar": {
              "type": "avatar"
          }
      }
  }
  ```
</CodeGroup>

The response includes all variables of the template along with their corresponding types.

### Generate a Preview Video

Generate a preview video using template\_id and variables data. This endpoint returns immediately with the job in a `pending` state. You can either poll the job status or use a webhook to get notified when the preview is ready.

<CodeGroup>
  ```bash Request [expandable] theme={null}
  curl --request POST \
    --url 'https://api.creatify.ai/api/custom_template_jobs/preview_async/' \
    --header 'Content-Type: application/json' \
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: your-api-key' \
    --data '{
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8",
      "variables": {
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://fastly.picsum.photos/id/237/500/500.jpg?hmac=idOEkrJhLd7nEU5pNrAGCyJ6HHJdR_sit1qDt5J3Wo0"
              }
          },
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          }
      },
      "name": "abc",
      "model_version": "aurora_v1_fast",
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc"
  }'
  ```

  ```json Response [expandable] theme={null}
  {
      "id": "cce08fc5-c2c2-4d7b-95b5-3997e4065506",
      "created_at": "2025-05-19T13:20:18.003143-07:00",
      "updated_at": "2025-05-19T13:20:18.192709-07:00",
      "name": "abc",
      "variables": {
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/audios/584ea32f.mp3"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/images/5c4377d4.jpg"
              }
          },
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          }
      },
      "media_job": "81f88ecd-a635-4203-9f0c-0a83678ee224",
      "video_output": null,
      "preview": null,
      "failed_reason": null,
      "credits_used": 0,
      "status": "pending",
      "progress": 0,
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc",
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8"
  }
  ```
</CodeGroup>

Once submitted, poll the job status using `GET /api/custom_template_jobs/{id}/` until the `preview` field is populated. Alternatively, if you provided a `webhook_url`, you will receive a callback when the preview is ready (see [Webhook for Video Updates](#webhook-for-video-updates) below).

### Render the Video

After generating the preview, render the final video:

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url 'https://api.creatify.ai/api/custom_template_jobs/cce08fc5-c2c2-4d7b-95b5-3997e4065506/render/'
    --header 'Content-Type: application/json'
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: you-api-key'
    --data '{}'
  ```

  ```json Response [expandable] theme={null}
  {
      "id": "cce08fc5-c2c2-4d7b-95b5-3997e4065506",
      "created_at": "2025-05-19T13:20:18.003143-07:00",
      "updated_at": "2025-05-19T13:20:18.192709-07:00",
      "name": "abc",
      "variables": {
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/audios/584ea32f.mp3"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/images/5c4377d4.jpg"
              }
          },
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          }
      },
      "media_job": "81f88ecd-a635-4203-9f0c-0a83678ee224",
      "video_output": null,
      "preview": "https://app.creatify.ai/preview?layout=videos/20250519/190628d8-4868-46db-ad9c-f1e4a8897933.json",
      "failed_reason": null,
      "credits_used": 1,
      "status": "pending",
      "progress": 0,
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc",
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8"
  }
  ```
</CodeGroup>

### Generate and Render Directly

Generate and render the video directly without preview:

<CodeGroup>
  ```bash Request [expandable] theme={null}
  curl --request POST \
    --url 'https://api.creatify.ai/api/custom_template_jobs/'
    --header 'Content-Type: application/json'
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: you-api-key'
    --data '{
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8",
      "variables": {
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://fastly.picsum.photos/id/237/500/500.jpg?hmac=idOEkrJhLd7nEU5pNrAGCyJ6HHJdR_sit1qDt5J3Wo0"
              }
          },
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          }
      },
      "name": "abc",
      "model_version": "aurora_v1_fast",
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc"
  }'
  ```

  ```json Response [expandable] theme={null}
  {
      "id": "cce08fc5-c2c2-4d7b-95b5-3997e4065506",
      "created_at": "2025-05-19T13:20:18.003143-07:00",
      "updated_at": "2025-05-19T13:20:18.192709-07:00",
      "name": "abc",
      "variables": {
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/audios/584ea32f.mp3"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/images/5c4377d4.jpg"
              }
          },
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          }
      },
      "media_job": "81f88ecd-a635-4203-9f0c-0a83678ee224",
      "video_output": null,
      "preview": null,
      "failed_reason": null,
      "credits_used": 0,
      "status": "pending",
      "progress": 0,
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc",
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8"
  }
  ```
</CodeGroup>

### Check Video Status

Poll the video generation status. Once the status is `done`, you can download the video, the link of the video is in the `video_output` field.

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.creatify.ai/api/custom_template_jobs/cce08fc5-c2c2-4d7b-95b5-3997e4065506/'
    --header 'X-API-ID: your-api-id' \
    --header 'X-API-KEY: you-api-key'
  ```

  ```json Response [expandable] theme={null}
  {
      "id": "cce08fc5-c2c2-4d7b-95b5-3997e4065506",
      "created_at": "2025-05-19T13:20:18.003143-07:00",
      "updated_at": "2025-05-19T13:20:18.192709-07:00",
      "name": "abc",
      "variables": {
          "TEXT": {
              "type": "text",
              "properties": {
                  "content": "Inline Text End"
              }
          },
          "audio": {
              "type": "audio",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/audios/584ea32f.mp3"
              }
          },
          "image": {
              "type": "image",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/images/5c4377d4.jpg"
              }
          },
          "video": {
              "type": "video",
              "properties": {
                  "url": "https://d35ghwdno3nak3.cloudfront.net/videos/6e9807c118f6f3e4ec64ef7f07a108d23fbfbb530ffa6ef7a3f67554c3bc28db.mp4"
              }
          },
          "avatar": {
              "type": "avatar",
              "properties": {
                  "avatar_id": "18fccce8-86e7-5f31-abc8-18915cb872be"
              }
          },
          "voiceover": {
              "type": "voiceover",
              "properties": {
                  "voice_id": "5ae737ae-e9af-469f-a1e4-7c41ffdbc3a7"
              }
          },
          "scene_text": {
              "type": "text",
              "properties": {
                  "content": "Inline Text Scene"
              }
          }
      },
      "media_job": "81f88ecd-a635-4203-9f0c-0a83678ee224",
      "video_output": "https://s3.us-west-2.amazonaws.com/remotionlambda-uswest2-30tewi8y5c/renders/8bnxcpw0ay/output.mp4",
      "preview": "https://app.creatify.ai/preview?layout=videos/20250519/f5b8dd9a-d3a7-49c6-8d36-f0d20f75943d.json",
      "failed_reason": "",
      "credits_used": 5,
      "status": "done",
      "progress": 1,
      "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc",
      "template_id": "f74f67a5-5008-46c9-b4a9-d5aebff142a8"
  }
  ```
</CodeGroup>

### Webhook for Video Updates

If you specified a webhook URL, you will receive a callback when the video is ready:

```json theme={null}
{
  "id": "cce08fc5-c2c2-4d7b-95b5-3997e4065506",
  "status": "done",
  "failed_reason": "",
  "video_output": "https://s3.us-west-2.amazonaws.com/remotionlambda-uswest2-30tewi8y5c/renders/rhflal3fwb/output.mp4"
}
```