# Visual

## 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 [API Dashboard](https://my.blotato.com/api-dashboard) 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](https://help.blotato.com/api/n8n/faqs#im-using-an-older-template-with-texttoimagemodel-and-imagetovidemodel-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 settings from the web app are NOT applied automatically to API template calls. To get on-brand results, include your brand instructions directly in the `prompt` parameter (e.g., "use blue and white colors, modern minimalist style"). See [Brand Kit](/settings/brand-kit.md) for details.

### 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>Applies your brand colors, tone, and style to the generated visual. Requires a brand kit configured in the web app. See <a href="/pages/QhZFfAHADu2LfTAPBSjA">Brand Kit</a>.</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
```

**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 [Get Visual Status](/api/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.

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

{
  "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f",
  "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:

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

{
  "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f",
  "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:

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

{
  "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f",
  "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](/api/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

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 [Get Visual Status](/api/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](/api/create-video/find-video.md) for full response details.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.