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.

Quickstart

Prerequisite

  • You need a creatify.ai account with API access.
  • You need to go through the Get your API key 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


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

Image


On Creatify.ai, use avatar image API variable to dynamically change the image in your video.

Video


On Creatify.ai, use avatar video API variable to dynamically change the video clip in your video.

Audio


On Creatify.ai, use audio API variable to dynamically change background music in your video.

Text (Overlay Text or Scene Text)



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:

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


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

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'

Get Custom Template Details

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

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'

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:

curl --request POST \
  --url 'https://api.creatify.ai/api/custom_template_jobs/preview/'
  --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",
    "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc"
}'

Render the Video

After generating the preview, render the final video:

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 '{}'

Generate and Render Directly

Generate and render the video directly without preview:

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",
    "webhook_url": "https://webhook.site/d94ac4fd-2384-4c21-b35d-2feb4f698cbc"
}'

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.

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'

Webhook for Video Updates

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

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