# Create a new motion graphics video generation job
Source: https://docs.hera.video/api-reference/endpoint/create-a-new-motion-graphics-video-generation-job

POST /videos
Creates a new motion graphics generation job. Submit your prompt and desired output formats to queue a video for generation.



# Retrieve the status of a motion graphics video
Source: https://docs.hera.video/api-reference/endpoint/retrieve-the-status-of-a-motion-graphics-video

GET /videos/{video_id}
Retrieve the export status, details, and output URLs for a generated video job using its ID.



# Upload a file
Source: https://docs.hera.video/api-reference/endpoint/upload-a-file

POST /files
Upload a file (image, video, audio, font, or CSV) to be used when creating videos. The returned URL can be used in POST /videos.



# Introduction
Source: https://docs.hera.video/api-reference/introduction



> Create and manage AI-generated motion graphics programmatically.

The Hera REST API enables you to generate motion graphics videos using simple HTTP requests. You can submit a video creation job and check its export status from your application or workflow.

## Endpoints

* **POST /videos**: Submit a new motion graphics job for generation (asynchronous).
* **GET /videos/\{video\_id}**: Retrieve the status for a specific video job.

## Authentication

Generate an API key in the [developer settings](https://app.hera.video/settings/developers).

All API requests must include your API key in the `x-api-key` HTTP header.

Example:

```
x-api-key: YOUR_API_KEY
```

API keys can be obtained on request. Keep your API keys secret; do not expose them in client-side code or public repositories.

<Note>
  Looking for support or have questions? Email us at [support@hera.video](mailto:support@hera.video).
</Note>


# MCP Server
Source: https://docs.hera.video/mcp-server

Connect Hera to your AI coding assistant via the Model Context Protocol.

The Hera MCP server lets AI assistants generate motion graphics videos on your behalf. It exposes the same capabilities as the [REST API](/api-reference/introduction), but through the standardized [Model Context Protocol](https://modelcontextprotocol.io/) — so your AI tools can call Hera directly.

## Prerequisites

* A Hera API key (see [Authentication](/api-reference/introduction#authentication))

## Available tools

The MCP server exposes three tools:

| Tool           | Description                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `create_video` | Create a new video generation job from a text prompt and output configurations. Returns a `video_id` for polling. |
| `get_video`    | Check the status of a video job and retrieve download URLs for completed outputs.                                 |
| `upload_file`  | Upload a file (image, video, audio, font, or CSV) for use as model input. Returns a hosted URL.                   |

## Setup

### Install with add-mcp

Install the MCP server for all your coding agents:

```bash theme={null}
npx add-mcp https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
```

<Tabs>
  <Tab title="Claude Desktop">
    Open **Claude Desktop → Settings → Developer → Edit Config** (this opens `claude_desktop_config.json`), then add the Hera server under `mcpServers`:

    ```json theme={null}
    {
      "mcpServers": {
        "hera-video": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.hera.video/mcp", "--header", "x-api-key: YOUR_API_KEY"]
        }
      }
    }
    ```

    Save the file and restart Claude Desktop to load the Hera MCP.
  </Tab>

  <Tab title="Claude Code">
    Run the following command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http hera https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Codex">
    Run the following command in your terminal:

    ```bash theme={null}
    codex mcp add hera -- npx -y mcp-remote https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor">
    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=hera&config=eyJ1cmwiOiJodHRwczovL21jcC5oZXJhLnZpZGVvL21jcCIsInR5cGUiOiJodHRwIiwiaGVhZGVycyI6eyJ4LWFwaS1rZXkiOiJZT1VSX0FQSV9LRVkifX0="><svg><path /><polyline /><line /></svg> Install in Cursor</a>

    To open Cursor and automatically add the Hera MCP, click install. Alternatively, add the following to your `.cursor/mcp.json` file in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "hera": {
          "url": "https://mcp.hera.video/mcp",
          "type": "http",
          "headers": {
            "x-api-key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    <a href="vscode:mcp/install?%7B%22name%22%3A%22hera%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.hera.video%2Fmcp%22%2C%22headers%22%3A%7B%22x-api-key%22%3A%22YOUR_API_KEY%22%7D%7D"><svg><path /><polyline /><line /></svg> Install in VS Code</a>

    To open VS Code and automatically add the Hera MCP, click install. Alternatively, add the following to your `.vscode/mcp.json` file in your project:

    ```json theme={null}
    {
      "servers": {
        "hera": {
          "type": "http",
          "url": "https://mcp.hera.video/mcp",
          "headers": {
            "x-api-key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other">
    MCP is an open protocol supported by many clients. Use the server URL `https://mcp.hera.video/mcp` and pass your API key via the `x-api-key` header. For example, a client might accept the following configuration:

    ```json theme={null}
    {
      "hera": {
        "url": "https://mcp.hera.video/mcp",
        "headers": {
          "x-api-key": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your actual API key.

## Example workflow

Once connected, you can ask your AI assistant to generate videos naturally:

> "Create a 10-second 1080p MP4 video of a spinning globe with a blue gradient background"

Behind the scenes, the assistant will:

1. Call `create_video` with your prompt and output settings
2. Receive a `video_id`
3. Poll `get_video` until the status is `success`
4. Return the download URL

## Tool reference

### create\_video

Creates a new video generation job.

**Parameters:**

| Parameter              | Type      | Required | Description                                                                         |
| ---------------------- | --------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt`               | string    | Yes      | Text prompt describing the video to generate.                                       |
| `outputs`              | array     | Yes      | 1-10 output configurations (see below).                                             |
| `reference_image_url`  | string    | No       | URL of a reference image.                                                           |
| `reference_image_urls` | string\[] | No       | Up to 5 reference image URLs.                                                       |
| `reference_video_url`  | string    | No       | URL of a reference video.                                                           |
| `duration_seconds`     | number    | No       | Duration in seconds (1-120).                                                        |
| `style_id`             | string    | No       | Style ID for consistent branding.                                                   |
| `parent_video_id`      | string    | No       | Video or template ID to use as a base.                                              |
| `assets`               | array     | No       | Array of asset objects (`{ type, url }`) to include. Use `upload_file` to get URLs. |

**Output configuration:**

| Field          | Type   | Options                               |
| -------------- | ------ | ------------------------------------- |
| `format`       | string | `mp4`, `prores`, `webm`, `gif`        |
| `aspect_ratio` | string | `16:9`, `9:16`, `1:1`, `4:5`          |
| `fps`          | string | `24`, `25`, `30`, `60`                |
| `resolution`   | string | `360p`, `480p`, `720p`, `1080p`, `4k` |

**Returns:** `video_id` and `project_url`.

### get\_video

Retrieves the status and download URLs for a video job.

**Parameters:**

| Parameter  | Type   | Required | Description                              |
| ---------- | ------ | -------- | ---------------------------------------- |
| `video_id` | string | Yes      | The video ID returned by `create_video`. |

**Returns:** `video_id`, `status` (`in-progress`, `success`, or `failed`), `project_url`, and an `outputs` array with individual status, download URL, config, and error (if any).

### upload\_file

Uploads a remote file to Hera's CDN for use as model input. For local files, pass the local path and the tool will return a ready-to-use `curl` command.

**Parameters:**

| Parameter   | Type   | Required | Description                                                                                      |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `url`       | string | Yes      | HTTP or HTTPS URL of the file to upload. For local files, pass the path to get a `curl` command. |
| `file_name` | string | No       | Custom filename (e.g. `logo.png`). Inferred from the URL if omitted.                             |

**Supported types:** images (PNG, JPEG, GIF, SVG, WebP, BMP), videos (MP4, MPEG, WebM, MOV, AVI, FLV, MPG, WMV, 3GP), audio (MP3, WAV, AAC), fonts (TTF, OTF, EOT, WOFF, WOFF2), and CSV. Max size: 10 MB.

**Returns:** `url` — the hosted URL to pass to `create_video` fields like `reference_image_url`, `reference_image_urls`, `reference_video_url`, or `assets`.

<Note>
  Looking for support or have questions? Email us at [support@hera.video](mailto:support@hera.video).
</Note>