Visual

Create a visual from a template using validated inputs or a prompt, then retain the creation ID for status lookup.

Migrating from the Old API Format

If you are getting this error: body.textToImageModel must be object, body.imageToVideoModel must NOT be valid

Your workflow is using an outdated request format. The old POST /v2/videos/creations endpoint with textToImageModel and imageToVideoModel as string fields no longer works.

Switch to the template system using POST /v2/videos/from-templates:

1. Browse available templates at my.blotato.com/videos/new

2. In n8n or Make, replace the old node with the Blotato "Create Visual" node

3. Select your template from the dropdown (start with a carousel — it renders in seconds)

4. Open the Logs to inspect the exact JSON payload each template expects

5. Override inputs one by one to customize

For AI story videos, choose the template named "AI Video with AI Voice."

See also: n8n FAQ — textToImageModel and imageToVideoModel

---

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.

Brand Kit is opt-in. Send a nonempty prompt and useBrandKit: true to include brand context when generating template inputs. An omitted or null brandId uses the primary brand. Without these conditions, include the required brand instructions in your prompt. MCP does not expose the same brand fields. See Brand Kit.

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.
isDraft	boolean	❌	Save as draft without rendering. Default: false.
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.
title	string	❌	A human-readable title for the generated video.
useBrandKit	boolean	❌	Default: false. With a nonempty prompt, includes compiled brand context during template input generation. Requires a configured brand. See Brand Kit.
brandId	string | null	❌	Brand ID for prompt-based generation with useBrandKit enabled. Omitted or null selects the primary brand.

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

The template list includes premade Blotato visual templates only. User-generated visual templates created or edited in the Blotato web app are not available in n8n, Make.com, MCP, or the /v2/videos/templates endpoint. Use a premade Blotato visual template from the dropdown or templates endpoint.

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	Case-insensitive text search in template name or description. Characters are matched literally. Ignored when id is supplied.
id	string	Optional template ID to get a specific template.

Inspect inputs without generating a visual

Template lookup is read-only. Do not execute a blank Create Visual request to learn the schema. Generation is a separate operation which consumes credits.

1. Send the REST lookup below.

2. Match the result to the requested output.

3. Retain its complete id.

4. Read its inputs specification for field names, nested types, defaults, allowed values, and limits.

5. Build the creation request only after confirming those inputs and the user's authorization to generate.

GET /v2/videos/templates?search=AI%20Video%20with%20AI%20Voice&fields=id,name,description,inputs HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY

Search matches text literally, without case sensitivity. For an exact lookup, pass the returned id instead. An empty items array means no matching template was returned. Do not guess another ID or submit an empty templateId.

With fields=id,name,description,inputs, the response includes the template's name.

These templates use different input structures:

Template	Content inputs
AI Video with AI Voice	scenes, each with script and mediaSource
Image Slideshow with Text Overlays	slides, each with imageSource and optional textOverlay
Instagram Carousel Slideshow	slidePrompts, where each entry is an image prompt string
Quote Card with Monocolor Background	title and quotes, where each quote is a string

Changing templateId also requires checking the new template's input schema. slides, slidePrompts, and scenes are not interchangeable.

For an error such as scenes.0: missing object, compare the submitted value at the reported path with the selected template's specification. Increasing wait time does not fix an input-validation error.

Responses

Success Response

Status Code: 201 Created

Visual creation is scheduled on the queue. To check status, poll the Get Visual Status endpoint.

Response Body:

{
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queueing"
  }
}

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 30 requests / 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
blotato-api-key: YOUR_API_KEY

{
  "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
blotato-api-key: YOUR_API_KEY

{
  "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
blotato-api-key: YOUR_API_KEY

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

Browse all templates with parameters and examples in the Visual Templates catalog. You can also use the /v2/videos/templates endpoint to get the current list programmatically. Common templates include:

Template Type	Description
Image Slideshow	Create slideshows from images with text overlays
Instagram Carousel Slideshow	AI-generated image carousels from text prompts
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

AI video renders take up to 10-15 minutes. A long render is normal and does not mean the request failed. Keep polling until the status reads done or the response includes error. If error is set, generation has stopped and the status will not change again, even if status is not a final status. If your AI agent reports the render as stuck or failing without an error, nudge it to check the status again before retrying.

If you're still having trouble generating a visual, 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 Get Visual Status endpoint to check its status:

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

Status values (in order):

• queueing - Waiting to be processed

• generating-script - AI is generating the script

• script-ready - Script is ready, generating media

• generating-media - Media is being generated

• media-ready - Media is ready, exporting

• exporting - Final export in progress

• done - Complete. Use mediaUrl or imageUrls from the response.

• creation-from-template-failed - Generation failed

See Get Visual Status for full response details.