> For the complete documentation index, see [llms.txt](https://hourone.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hourone.gitbook.io/api-docs/dynamic-quick-start.md).

# Dynamic - Quick Start

## Get your API keys

{% content-ref url="/pages/ZJ1yPGsS9kK7l4YceevL" %}
[Get Your API Keys](/api-docs/get-your-api-keys.md)
{% endcontent-ref %}

## Create your first Dynamic API request

Login to the HourOne platform <https://app.hourone.ai>&#x20;

Video in HourOne is based on a template a template will define the look-and-feel of the video and the available layouts for that video.

Each layout defines the graphical elements (audio, video, images, text, and location of the avatar)

To start, either create a project from the template section or open a pre-existing one.

The steps to create a dynamic video are,

1. [Toggle developer mode](#toggle-the-developer)
2. [Copy base request](#base-request)
3. [Build scenes](#building-scenes)
4. [Set global elements](#global-elements)
5. [Set root elements](#root-elements)

### Toggle the developer

Toggle the developer mode on.

<figure><img src="/files/yk5TDKkc2YTJXeAcavJg" alt=""><figcaption></figcaption></figure>

### Base Request

Copy the *base* request structure, we will use this base to modify your video dynamically, click on the developer button next to the video title.

<figure><img src="/files/a4NIQJU9gngSkDoSWJaX" alt=""><figcaption></figcaption></figure>

Now either copy the CURL or JSON body

<figure><img src="/files/ito1aaP0TGS7cjtH9KCp" alt=""><figcaption></figcaption></figure>

### Building scenes

Create your first scene, start by clicking the *scene* section in the drawers.

The structure of a scene can be seen in the example below&#x20;

```json
{
            "name": "Premium Pet Food at Discounted Prices",
            "type": "create_scene",
            "layout_id": "64669fd265d3927ea592dd25",
            "media_elements": [
                {
                    "id": "USER-VISUAL-001",
                    "url": "https://cdn.filestackcontent.com/7BujNsJ8R2SPf09VagIR"
                }
            ],
            "texts_elements": [
                {
                    "id": "TEXT-001",
                    "text": "Looking for quality food to keep your furry friends happy?"
                }
            ],
            "transcript": "Hey pet owners! Looking for quality food to keep your furry friends happy?"
}
```

1. &#x20;***layout\_id*** is retrieved by clicking the developer icon on the layout preview

<figure><img src="/files/9yCENLx9ta8OPkRgVXi8" alt=""><figcaption></figcaption></figure>

2. ***media\_elements*** are either videos or images that will appear within the layout, the elements are mandtory and <mark style="color:red;">can not</mark> be left empty. The ***media\_elements*** key is a root key of a type array, each element in the array corresponds to a media element within the layout, the ***id*** of the element can be retrieved by clicking the developer icon on the media element in the **Images and video** section in the **Scene** panel.&#x20;

<figure><img src="/files/CrolpzydWmHsm7Sa3VqP" alt=""><figcaption></figcaption></figure>

The object that describes a media element is a simple JSON (see below) where the ***id*** is obtained as described above and the URL is a <mark style="color:purple;">**publicly**</mark> accessible URL that you provide.

```json
{
                    "id": "USER-VISUAL-001",
                    "url": "https://cdn.filestackcontent.com/7BujNsJ8R2SPf09VagIR"
}
```

{% hint style="info" %}
If no ***id*** is provided for the element the assignment of elements to the IDs will be automatic upon a preconfigured internal setting, but you <mark style="color:red;">**must**</mark> provide the exact amount of media elements as in the layout.
{% endhint %}

3. **texts\_elements** are any form of a textual element in the layout either a title, subtitle, or paragraph. The elements are not mandtory and therefore can be left empty, an empty element will not show on the video. The **texts\_elements** key is a root key of a type array, each element in the array corresponds to a text element within the layout, the ***id*** of the element can be retrieved by clicking the developer icon on the media element in the **Titles** section in the **Scene** panel.&#x20;

<figure><img src="/files/JCMVSnImdyd4jyrs4764" alt=""><figcaption></figcaption></figure>

The object that describes a text element is a simple JSON (see below) where the ***id*** is obtained as described above and the text key.

```json
{
                    "id": "TEXT-001",
                    "text": "Looking for quality food to keep your furry friends happy?"
}
```

{% hint style="info" %}
If no ***id*** is provided for the element the assignment of elements to the IDs will be automatic upon a preconfigured internal setting.
{% endhint %}

4. **transcript** the scene's transcript must contain less than 1000 characters, this is what the avatar will say during the video.&#x20;

{% hint style="danger" %}
This field is optional <mark style="color:red;">only and only</mark> if the **voice\_recording\_url** is provided.
{% endhint %}

5. **voice\_recording\_url** is an optional field that instead of using transcript and text-to-speech providers. The voice recording is provided via <mark style="color:purple;">**publicly**</mark> available URL of a **wav** file. &#x20;
6. **name** the scene name for internal use.
7. **type** should be set to **create\_scene**

### Global Elements

These elements are global elements that appear in the video.

```json
"global_media_elements": [
        {
            "id": "logo",
            "url": "https://cdn.filestackcontent.com/07vBfMKSi6nQ6PUaDTYj"
        },
        {
            "id": "url_intro",
            "url": "https://cdn.filestackcontent.com/lym8uQ7BRnKaPXcKfGkl"
        },
        {
            "id": "url_outro",
            "url": "https://cdn.filestackcontent.com/lym8uQ7BRnKaPXcKfGkl"
        },
        {
            "id": "music",
            "media_id": "62d696daeb21945872627730"
        }
    ]
```

The ***IDs*** for the elements can be found in the **Brand** panel (all are optional),

<figure><img src="/files/yJEioZy1eqHjE1iHfmVh" alt=""><figcaption></figcaption></figure>

The **music** id is retrieved from the **music** panel

<figure><img src="/files/NbvU7k7fmT7RONYpQ0yh" alt=""><figcaption></figcaption></figure>

### Root elements

```json
{
    "type": "create",
    "name": "Untitled video - Product Promotion",
    "template_id": "646ceddac43ac37b398c0637",
    "palette_id": "646ceadbf20e3a40f6b5586e",
    "character_id": "63fde5179f9f183d0fc031bb",
    "voice_id": "b7f2e3c4-4a78-3667-93e8-f7c5b19eb85d",
    ...
}
```

1. **type** should be set **create**
2. **name** the name of the video
3. **template\_id** the video template will determine the look-and-feel and the layouts, can be retrieved from the **Template** panel.
4. **palette\_id(optional)** These are the colors that will be used in the video, this can be retrieved from the **Style** panel, and color can be sent in the request in the form of a hex colors **palette**

<figure><img src="/files/WDT8kMoAU8O7fiVTVVJ5" alt=""><figcaption></figcaption></figure>

5. **palette(optional) - an** array of custom hex colors, instead of using palette\_id:&#x20;

   The palette size must match the template; otherwise, you will receive an error indicating the expected palette size.

   palette: \[{"color": "#826f3b"}, {"color":"#295c4d"}]
6. **voice\_id**

<figure><img src="/files/1R5n0diea9f3X5DVrA85" alt=""><figcaption></figcaption></figure>

6. **character\_id**

<figure><img src="/files/FFZ3GJrdd6hcfKAAchf8" alt=""><figcaption></figcaption></figure>

7. **palette** is an optional field that can be sent if no **palette\_id** is defined in the form of&#x20;

```json
{
    "palette" : ["#FF0000","#00FF00"...]
...
}
```

### Multiple characters and voices

You can use multiple characters and voices by setting the **character\_id** and **voice\_id** on the scene. If these are not specified on the scene, the values will be taken from the root.

## Make your first request

Now you can take the request you built and use your favorite API testing tool such as Postman.

<figure><img src="/files/Eo5Wwi1x1YmFzY4YwciW" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Don't forget to enter your API key
{% endhint %}

Once you have modified the JSON use your API key to make a call to the videos endpoint.

{% hint style="info" %}
**Good to know:** the DraftID of your project can be found in the project’s editor URL
{% endhint %}

{% hint style="warning" %}
The schema for Dynamic Videos is **NewVideoRequest** in the OpenAPI docs
{% endhint %}

{% openapi src="<https://api.makereals.com/api/v1/openapi.json>" path="/videos" method="post" %}
<https://api.makereals.com/api/v1/openapi.json>
{% endopenapi %}

## Get the video status

Using the **id** received in the video creation call you will be able to poll the status of your video by calling the following API<br>

{% hint style="info" %}
You can always go to the HourOne platform and see your videos and status there.
{% endhint %}

{% openapi src="<https://api.makereals.com/api/v1/openapi.json>" path="/videos" method="get" %}
<https://api.makereals.com/api/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://api.makereals.com/api/v1/openapi.json>" path="/videos/{video\_id}" method="get" %}
<https://api.makereals.com/api/v1/openapi.json>
{% endopenapi %}