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.