🔡Dynamic - Quick Start

Get your API keys

🔑Get Your API Keys

Create your first Dynamic API request

Login to the HourOne platform https://app.hourone.ai

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

2. Copy base request

3. Build scenes

4. Set global elements

5. Set root elements

Toggle the developer

Toggle the developer mode on.

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.

Now either copy the CURL or JSON body

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

{
            "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. layout_id is retrieved by clicking the developer icon on the layout preview

1. media_elements are either videos or images that will appear within the layout, the elements are mandtory and can not 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.

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 publicly accessible URL that you provide.

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

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 must provide the exact amount of media elements as in the layout.

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

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.

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

If no id is provided for the element the assignment of elements to the IDs will be automatic upon a preconfigured internal setting.

1. transcript the scene's transcript must contain less than 1000 characters, this is what the avatar will say during the video.

This field is optional only and only if the voice_recording_url is provided.

1. voice_recording_url is an optional field that instead of using transcript and text-to-speech providers. The voice recording is provided via publicly available URL of a wav file.

2. name the scene name for internal use.

3. type should be set to create_scene

Global Elements

These elements are global elements that appear in the video.

"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),

The music id is retrieved from the music panel

Root elements

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

1. palette(optional) - an array of custom hex colors, instead of using palette_id:

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

   palette: [{"color": "#826f3b"}, {"color":"#295c4d"}]

2. voice_id

1. character_id

1. palette is an optional field that can be sent if no palette_id is defined in the form of

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

Don't forget to enter your API key

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

Good to know: the DraftID of your project can be found in the project’s editor URL

The schema for Dynamic Videos is NewVideoRequest in the OpenAPI docs

Create Video

post

Create a video based on a source draft or a recipe_id

Authorizations

Body

one ofoptional

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v1/videos' \
  --header 'api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "override",
    "name": "text",
    "source_draft_id": "text",
    "recipe_id": "text",
    "folder_id": "text",
    "palette_id": "text",
    "character_id": "text",
    "voice_id": "text",
    "scenes": [
      {
        "name": "text",
        "type": "override_scene",
        "media": [
          "text"
        ],
        "texts": [
          "text"
        ],
        "transcript": "text",
        "voice_recording_url": "text"
      }
    ],
    "logo_url": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "correlation_id": "text"
  }'

201

422

201

{
  "id": "text",
  "name": "text",
  "status": "started",
  "progress": 1,
  "req_id": "text",
  "draft_id": "text",
  "source_draft_id": "text",
  "recipe_id": "text",
  "template_id": "text",
  "palette_id": "text",
  "character_id": "text",
  "voice_id": "text",
  "scenes": [
    {
      "name": "text",
      "type": "override_scene",
      "media": [
        "text"
      ],
      "texts": [
        "text"
      ],
      "transcript": "text",
      "voice_recording_url": "text"
    }
  ],
  "video_player_url": "text",
  "download_url": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "correlation_id": "text",
  "palette": [
    {
      "color": "text"
    }
  ],
  "global_media_elements": [
    {
      "id": "text",
      "url": "https://example.com",
      "media_id": "text"
    }
  ],
  "duration": 1,
  "thumbnail_url": "text"
}

Successful Response

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

You can always go to the HourOne platform and see your videos and status there.

List Videos

get

Get videos

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/videos' \
  --header 'api-key: YOUR_API_KEY'

200

200

[
  {
    "id": "text",
    "name": "text",
    "status": "started",
    "progress": 1,
    "req_id": "text",
    "draft_id": "text",
    "source_draft_id": "text",
    "recipe_id": "text",
    "template_id": "text",
    "palette_id": "text",
    "character_id": "text",
    "voice_id": "text",
    "scenes": [
      {
        "name": "text",
        "type": "override_scene",
        "media": [
          "text"
        ],
        "texts": [
          "text"
        ],
        "transcript": "text",
        "voice_recording_url": "text"
      }
    ],
    "video_player_url": "text",
    "download_url": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "correlation_id": "text",
    "palette": [
      {
        "color": "text"
      }
    ],
    "global_media_elements": [
      {
        "id": "text",
        "url": "https://example.com",
        "media_id": "text"
      }
    ],
    "duration": 1,
    "thumbnail_url": "text"
  }
]

Successful Response

Get Video By Id

get

Get video by id

Authorizations

Path parameters

video_idstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/videos/{video_id}' \
  --header 'api-key: YOUR_API_KEY'

200

422

200

{
  "id": "text",
  "name": "text",
  "status": "started",
  "progress": 1,
  "req_id": "text",
  "draft_id": "text",
  "source_draft_id": "text",
  "recipe_id": "text",
  "template_id": "text",
  "palette_id": "text",
  "character_id": "text",
  "voice_id": "text",
  "scenes": [
    {
      "name": "text",
      "type": "override_scene",
      "media": [
        "text"
      ],
      "texts": [
        "text"
      ],
      "transcript": "text",
      "voice_recording_url": "text"
    }
  ],
  "video_player_url": "text",
  "download_url": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "correlation_id": "text",
  "palette": [
    {
      "color": "text"
    }
  ],
  "global_media_elements": [
    {
      "id": "text",
      "url": "https://example.com",
      "media_id": "text"
    }
  ],
  "duration": 1,
  "thumbnail_url": "text"
}

Successful Response