Create Video /v2/videos/creations

Creating a Video

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /videos/creations

Method: POST

Description

This endpoint allows users to create a new video from a script, style and template.

Request

Request Body

The request body must contain the following fields:

Field

Type

Required

Description

template

object

Template specification. the id field must match exactly.

script

string

Script for the created video. The AI will automatically extract scenes and generate prompts from it. Could be as simple as "you wake up as a soldier" or as descriptive as you want (e.g. for "empty" template id). If you're using slides template, just put "1" as the value.

style

string

Style options: 'cinematic', 'apocalyptic', 'baroque', 'comicbook', 'cyberpunk', 'dystopian', 'fantasy', 'futuristic', 'gothic', 'grunge', 'horror', 'kawaii', 'mystical', 'noir', 'painterly', 'realistic', 'retro', 'surreal', and 'whimsical'. If you're using slides template, just put "cinematic" as the value.

animateFirstImage

boolean

Default: false. If true, the first image will be animated with Kling 1.6 pro model. Note that insufficient credits will result in the image not being animated.

animateAll

boolean

Default: false. If true, all the images will be animated. Note that insufficient credits will result in the image not being animated. Setting this option to true ignores animateFirstImage value

textToImageModel

replicate/black-forest-labs/flux-schnell

replicate/black-forest-labs/flux-dev replicate/black-forest-labs/flux-1.1-pro

replicate/black-forest-labs/flux-1.1-pro-ultra replicate/recraft-ai/recraft-v3 replicate/ideogram-ai/ideogram-v2 replicate/luma/photon

openai/gpt-image-1

Default: flux-dev for first image, and flux-schnell for the rest. Sets the text to image model for every AI image.

imageToVideoModel

fal-ai/framepack fal-ai/runway-gen3/turbo/image-to-video fal-ai/luma-dream-machine/image-to-video fal-ai/kling-video/v1.5/pro/image-to-video fal-ai/kling-video/v1.6/pro/image-to-video fal-ai/minimax-video/image-to-video fal-ai/minimax/video-01-director/image-to-video fal-ai/hunyuan-video-image-to-video fal-ai/veo2/image-to-video

Default: kling-1.6 pro. Sets the image to video model for every AI video generated.

template Object

Field

Type

Required

Description

id

empty base/pov/wakeup base/slides/quotecard

The ID of the template to use.

Template parameters

'base/pov/wakeup'

Field

Type

Required

Description

id

'base/pov/wakeup'

firstSceneText

string

Text of the first scene (Optional). Defaults to AI generated scene text.

captionPosition

'top' | 'bottom' | 'middle' | null

Text position. Pass null to remove the text completely.

'base/slides/quotecard'

Field

Type

Required

Description

id

'base/slides/quotecard'

scenes

Scene[]

List of scenes to generate. See the Scene model below.

captionPosition

'top' | 'bottom' | 'middle' | null

Text position. Pass null to remove the text completely.

Scene object type

Field

Type

Required

Description

prompt

string

Plain‑language description of the desired card (e.g. “inspiring quote about curiosity and space”). If you supply no other fields, the system uses an LLM to derive: 1) the exact quote text and 2) the text‑to‑image prompt for the background.

textToImagePrompt

string

Provide a specific prompt for the image generator (“wide‑angle Milky Way over desert in retro‑poster style”). When present, this replaces the image prompt the system would have created from prompt.

text

string

Provide the quote text yourself (“Adventure begins where plans end.”). When present, this replaces the quote the system would have created from prompt.

'empty'

Field

Type

Required

Description

id

'empty'

voiceId

string

ID of the narrator's voice. See the list of available voices here. If you do not specify the voice, the captions will render without the audio

captionPosition

'top' | 'bottom' | 'middle' | null

Caption position. Pass null to remove the captions completely.

Responses

Success Response

Status Code: 201 Created

Video creation is scheduled on the queue. To see the status, poll the Find Video endpoint.

Response Body:

{
  "item": {
    "id": "VIDEO ID",
    "status": "Queued"
  },
}

Error Responses

Too Many Requests

Post creation has a user-level rate limit of 1 request / minute to prevent spamming / abusing video creation.

Status Code: 429 Too many requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded, retry in 49 seconds"
}

Examples

1. Create a POV video

POST https://backend.blotato.com/v2/videos/creations HTTP/1.1
Content-Type: application/json
Headers:

{
  "script": "you wake up as a pharaoh",
  "style": "cinematic",
  "template": {
    "id": "base/pov/wakeup",
  }
}

2. Create a Quote Card Slideshow

POST https://backend.blotato.com/v2/videos/creations HTTP/1.1
Content-Type: application/json
Headers:

{
  "script": "1",
  "style": "cinematic",
  "template": {
    "id": "base/slides/quotecard",
    "captionPosition": "middle",
    scenes: [
      {
        "prompt": "feel down today - what to do"
      },
      {
        "prompt": "feel down today - what to do tomorrow"
      }
    }
  }
}

3. Create a Quote Card Slideshow - Custom Text

POST https://backend.blotato.com/v2/videos/creations HTTP/1.1
Content-Type: application/json
Headers:

{
  "script": "1",
  "style": "cinematic",
  "template": {
    "id": "base/slides/quotecard",
    "captionPosition": "middle",
    scenes: [
      {
        "prompt": "feel down today - what to do",
        "text": "A new day is better than the old day"
      },
      {
        "prompt": "feel down today - what to do tomorrow",
        "text": "A samoyed in hand is better than a manatee"
      }
    }
  }
}

Troubleshooting

If you are having troubles generating the video, or it's taking too long, navigate to https://my.blotato.com/videos/<YOUR_VIDEO_ID> to view the image / video and manually edit it.

Last updated