Create Video

Videos are generated from one or more templates used as clips, filling their layers with your data.

Endpoint

Method URI
POST https://api.placid.app/api/rest/videos

Request

{
  "webhook_success": "https://webhook.url",
  "passthrough": null,

  "clips": [
    {
        "template_uuid": "<template_uuid>",

        // - audio settings
        "audio" : "https://mp3url.mp3",
        "audio_duration" : "...", 
        "audio_trim_start" : "00:00:00", 
        "audio_trim_end" : "00:00:00",

        // - layer settings
        "layers": {
            "video": {
                "video": "https://videourl.mp4"
            },
            "img": {
                "image": "https://imageurl.jpg"
            },
            "subtitle": {
                "hide": true
            },
            "title": {
                "text": "Lorem Ipsum"
            }
            ...
        },
    },
    // ...
  ],

  "modifications": {
     "width": "<width>",
     "height": "<height>",
     "fps": "<fps>",
     "filename": "<filename>",
     "canvas_background": "blur"
  },
  "transfer": {
     "to": "s3",
     "key": "<your key>",
     "secret": "<your secret>",
     "region": "<region name>",
     "bucket": "<bucket name>",
     "visibility": "public",
     "path": "videos/video.mp4",
     "endpoint": "https://exampleendpoint.com"
  }
}
Field Values Description
webhook_success Webhook URL After the image is created Placid will POST the response to this Webhook URL
passthrough string or array Any data added to this parameter will be saved and sent in any subsequent webhooks and requests for this video (max-length is 1024 characters)
clips array of clip objects Your desired clips/templates; Add multiple templates to get a merged video
transfer Additionally transfer the generated image to your storage

Video content

The content of your video will be defined by an array of templates in your clips object.

Field Values
clips.*.template_uuid The ID of the template used for your clip
clips.*.audio URL of mp3 audio file for this clip
clips.*.audio_duration Set to auto to trim audio to video length; defaults to full to include the whole audio track
clips.*.audio_trim_start Timestamp of the trim start point 00:00:45 or with milliseconds 00:00:45.25
clips.*.audio_trim_end Timestamp of the trim end point 00:00:55 or with milliseconds 00:00:55.25
clips.*.layers View Layer Properties Dynamically change the content and properties of your template layers

Get your {template_uuid} from the template overview in the Templates tab of your Placid API project.

https://placid.app/images/placid-template-id.jpg

  • The API allows you to create a video from one or more clips / templates, merged in the order you define
  • You can fill one or more picture layers in your template with video files
  • You can fill one or more values into text layers of your template
  • Use animation and transition settings in the template editor
  • Total clip length will be dependent on your dynamic content
  • If you fill a clip with > 1 video, the shorter videos will loop automatically until the longest is finished
  • Audio tracks are taken from your source video(s)
  • Current max video length is 3 minutes (= 180 seconds)
  • If you do not define any width and height modifications, the video will be sized according to your first clip template's size
  • Differently sized clips will be set on a canvas background customizable via modifications below
  • ➡️ Learn more about Placid video settings, clip length and behaviour

Export / transfer

To transfer the generated video to your storage use the transfer object.

Field Values
transfer.to s3
transfer.key, transfer.secret Your credentials (Placid never stores them)
transfer.bucket Your bucket name
transfer.visibility public or private
transfer.path File path (Define the full video path starting from the root directory of your bucket, including filename and file extension. Placid will overwrite existing files in the specified directory!)

File modifications

To modify the generated video use the modifications object.

Field Values
modifications.format mp4
modifications.width Video width
Empty = auto
modifications.height Video height
Empty = auto
modifications.canvas_background Defaults to #000000; Enter hexcode or blur for blurred
modifications.fps Defaults to 25 fps; min 1 max 30
modifications.filename Filename of the generated video

Response

By default all videos are created async. Define a webhook_success URL or poll the polling_url of the response until the status of the response is finished.

{
    "id": 1,
    "status": "queued",
    "video_url": null,
    "polling_url": null
}
Field Values
id Unique video id for internal reference
status queued The request has been put into the queue.
finished The video has been created successfully.
error There was an error.
video_url URL to created video or null
polling_url Endpoint that you can GET poll for status updates

{info} We recommend storing created videos on your servers, as we only store them for a limited time.