Create Video /v2/videos/creations

Creating a Visual

Endpoint

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

URL: /videos/from-templates

Method: POST

Description

This endpoint creates a new visual (image or video) from a template. Templates define the structure and input parameters for generating visuals like slideshows, quote cards, tweet cards, and more.

You can provide input parameters manually, or use the optional prompt parameter to have AI automatically fill in the template inputs based on your description.

Request

Request Body

Field	Type	Required	Description
templateId	string	✅	The ID of the template to use. Get available templates from the /v2/videos/templates endpoint.
inputs	object	✅	Template-specific input parameters. Structure depends on the selected template. Can be an empty object {} if using the prompt parameter.
prompt	string	❌	Optional natural language prompt to auto-fill template inputs using AI. When provided, AI interprets your description and fills in the inputs automatically. Any manually provided inputs take precedence over AI-generated values.
render	boolean	❌	Whether to render the visual immediately. Default: true.
isDraft	boolean	❌	Save as draft without rendering. Default: false.

Getting Available Templates

To list all available templates and their input specifications:

GET https://backend.blotato.com/v2/videos/templates?fields=id,name,description,inputs

Query Parameters:

Field	Type	Description
fields	string	Comma-separated list of fields to include. Use id,name,description,inputs to get full template details.
search	string	Optional regex term to filter templates by name or description.
id	string	Optional template ID to get a specific template.

Responses

Success Response

Status Code: 201 Created

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

Response Body:

{
  "item": {
    "id": "VIDEO_ID",
    "status": "Queued"
  }
}

Error Responses

Not Found

Status Code: 404 Not Found

{
  "message": "Unknown template ID"
}

Too Many Requests

Visual creation has a user-level rate limit of 1 request / minute.

Status Code: 429 Too many requests

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

Examples

1. Create a Visual Using AI Prompt (Recommended)

The easiest way to create visuals is using the prompt parameter. AI will interpret your description and fill in the template inputs automatically.

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

{
  "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1",
  "inputs": {},
  "prompt": "Create a 5-slide carousel about productivity tips for remote workers. Use a modern, professional style with blue tones.",
  "render": true
}

2. Create a Visual with Manual Inputs

You can also specify inputs manually for full control:

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

{
  "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1",
  "inputs": {
    "slides": [
      {
        "imageSource": "https://example.com/image1.jpg",
        "textOverlay": "Slide 1: Introduction"
      },
      {
        "imageSource": "A serene mountain landscape at sunset",
        "textOverlay": "Slide 2: AI-generated image"
      }
    ],
    "textPosition": "center",
    "aiImageModel": "replicate/recraft-ai/recraft-v3"
  },
  "render": true
}

3. Combine Prompt with Manual Overrides

You can use prompt for most inputs while manually specifying certain values:

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

{
  "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1",
  "inputs": {
    "textPosition": "bottom",
    "textColor": "#FFFFFF"
  },
  "prompt": "Create a 3-slide motivational carousel about morning routines",
  "render": true
}

In this example, AI fills in the slides content, but textPosition and textColor use your manual values.

Available Templates

Use the /v2/videos/templates endpoint to get the current list of templates. Common templates include:

Template Type	Description
Image Slideshow	Create slideshows from images with text overlays
Quote Card	Generate quote cards with stylized backgrounds
Tweet Card	Create visual cards from tweet-style content
Tutorial Carousel	Step-by-step tutorial visuals
AI Story Video	AI-generated story videos with narration
Combine Clips	Merge multiple video clips

Template Input Types

Templates use various input types:

Type	Description	Example
text	Plain text string	"Hello world"
number	Numeric value	42
boolean	True/false	true
enum	Choice from predefined values	"top" | "center" | "bottom"
image	Image URL	"https://example.com/image.jpg"
video	Video URL	"https://example.com/video.mp4"
color	Hex color code	"#FF5733"
array	List of items	[{...}, {...}]
object	Nested object	{ "key": "value" }

Troubleshooting

If you're having trouble generating a visual or it's taking too long, navigate to https://my.blotato.com/videos/<YOUR_VIDEO_ID> to view and manually edit it.

Polling for Status

After creating a visual, poll the Find Video endpoint to check its status:

GET https://backend.blotato.com/v2/videos/creations/<VIDEO_ID>

Possible status values:

• Queued - Waiting to be processed

• Processing - Currently being generated

• Completed - Ready to use

• Failed - Generation failed