> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/rest-api-reference/create-video.md).

# 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](https://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](https://my.blotato.com/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](/integrations-and-automation-templates/n8n/faqs.md#im-using-an-older-template-with-texttoimagemodel-and-imagetovideomodel-parameters-do-these-still-work)

***

## 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](/settings/brand-kit.md).

### Request

#### Request Body

<table><thead><tr><th width="150">Field</th><th width="120">Type</th><th width="100">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>templateId</code></td><td><code>string</code></td><td>✅</td><td>The ID of the template to use. Get available templates from the <code>/v2/videos/templates</code> endpoint.</td></tr><tr><td><code>inputs</code></td><td><code>object</code></td><td>✅</td><td>Template-specific input parameters. Structure depends on the selected template. Can be an empty object <code>{}</code> if using the <code>prompt</code> parameter.</td></tr><tr><td><code>isDraft</code></td><td><code>boolean</code></td><td>❌</td><td>Save as draft without rendering. Default: <code>false</code>.</td></tr><tr><td><code>prompt</code></td><td><code>string</code></td><td>❌</td><td>Optional natural language prompt to auto-fill template inputs using AI. When provided, AI interprets your description and fills in the <code>inputs</code> automatically. Any manually provided <code>inputs</code> take precedence over AI-generated values.</td></tr><tr><td><code>render</code></td><td><code>boolean</code></td><td>❌</td><td>Whether to render the visual immediately. Default: <code>true</code>.</td></tr><tr><td><code>title</code></td><td><code>string</code></td><td>❌</td><td>A human-readable title for the generated video.</td></tr><tr><td><code>useBrandKit</code></td><td><code>boolean</code></td><td>❌</td><td>Default: false. With a nonempty prompt, includes compiled brand context during template input generation. Requires a configured brand. See <a href="/settings/brand-kit.md">Brand Kit</a>.</td></tr><tr><td><code>brandId</code></td><td><code>string | null</code></td><td>❌</td><td>Brand ID for prompt-based generation with useBrandKit enabled. Omitted or null selects the primary brand.</td></tr></tbody></table>

### 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. Call `blotato_list_design_templates` with `{"search":"AI Video with AI Voice"}`, or 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.

```http
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`.

MCP supplies `id`, `description`, and `inputs`. Do not depend on a `title` or `name` field in its result. REST with `fields=id,name,description,inputs` includes the template's `name`.

These templates use different input structures:

| Template                                                                                                    | Content inputs                                               |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [AI Video with AI Voice](/rest-api-reference/visuals/5903fe43-514d-40ee-a060-0d6628c5f8fd.md)               | `scenes`, each with `script` and `mediaSource`               |
| [Image Slideshow with Text Overlays](/rest-api-reference/visuals/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f.md)   | `slides`, each with `imageSource` and optional `textOverlay` |
| [Instagram Carousel Slideshow](/rest-api-reference/visuals/53cfec04-2500-41cf-8cc1-ba670d2c341a.md)         | `slidePrompts`, where each entry is an image prompt string   |
| [Quote Card with Monocolor Background](/rest-api-reference/visuals/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd.md) | `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](/rest-api-reference/create-video/find-video.md) endpoint.

**Response Body:**

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

#### Error Responses

**Not Found**

**Status Code:** `404 Not Found`

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

```json
{
  "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.

```http
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:

```http
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:

```http
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](/rest-api-reference/visuals.md) 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](/rest-api-reference/create-video/find-video.md) 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](/rest-api-reference/create-video/find-video.md) for full response details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.blotato.com/rest-api-reference/create-video.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.