<aside> 🔥 The Movio API gives you abilities to create, automate video by submitting json. You can access video editing abilities of movio.la by Movio API..

</aside>

Introduction

The Movio API gives you abilities to create, automate video with AI driven avatar by submiting json. You can access multi video editing abilities of movio.la by Movio API.

This documentation describes all of the available API calls and properties of the returned objects. If you have any questions, please reach out to [email protected].

<aside> 📢 At this time the movio API is unstable. This means that the way it works and the data it returns may change at any time. Breaking changes are rare, but do happen. Proper versioning will be introduced in a future release.

</aside>

Features

💬 Text to speech with 100+ voices supported
🌐 More than 50 languages supported
💁 Embed 10+ avatars to your videos.
👄 Lipsyncing speech to your avatar of choice
📹 Embed any videos(s) into your final video
🖼️ Embed any image(s) into your final video
🎞️ Multi scene videos
✨ Add transition between your scenes.
🔠 Support more than 20+ fonts of text.

Getting Started

Register a Movio Account

Before getting started, a movio account is needed. If you don’t have one, create a movio account and get start!

Obtaining an API Token

The Movio API uses X-Api-Key tokens to authorize requests. As an developer, you'll need to register a movio account at fisrt. Log into movio.la after registeration, click the Account button in the left bottom, the API token shows there.

<aside> ‼️ Keep the API token secret and safe. Anyone with this API Key can use the movio API as you. If it is compromised, please send an email to [email protected] and it can be deactivated or reseted.

</aside>

Sending your first API call

Movio API is authenticated with a token sent with each request. The header X-Api-Key must be include in every API call.

Request /api/v1/token.check to validate you X-Api-Key.

Here is the HTTP request

GET /api/v1/token.check HTTP/1.1
x-api-token: {MY_API_TOKEN}

You can use tools like curl to send the request:

curl --X POST "<https://craft-api.surreal-ai.com/pacific/api/token.check>" --header 'X-Api-Key: {api-token-here}'

The following reponse will be returned if the token is valid:

{
    "code": 100,
    "message": "Success"
}

Getting your first video

It’s pretty simple to get your first video by Movio API. the reqeust is


POST /api/v1/video.generate HTTP/1.1
X-Api-Key: {MY_API_TOKEN}

Post this json to https://craft-api.surreal-ai.com/pacific/api/v1/video.generate with your API token in HTTP X-Api-Key header.

{
  "background": "off_white",
  "clips": [
    {
      "avatar_name": "Mark-blueshirtfullbody-20220601",
      "avatar_style": "normal",
      "caption": true,
      "input_text": "Welcolme to movio API",
      "offset": {
        "x": 0,
        "y": 0
      },
      "scale": 1,
      "voice_name": "en-US-GuyNeural"
    },
    {
      "avatar_name": "Mark-blueshirtfullbody-20220601",
      "avatar_style": "normal",
      "caption": true,
      "input_text": "Use json to generate you own AI video now!",
      "offset": {
        "x": 0.2,
        "y": 0
      },
      "scale": 1,
      "voice_name": "en-US-GuyNeural"
    }
  ],
  "ratio": "16:9",
  "test": true,
  "version": "v1alpha"
}

You can also use curl comand to generate this video, replace {api-token-here} with your API token.

curl --location --request POST --X POST '<https://craft-api.surreal-ai.com/pacific/api/v1/video.generate>' \\
--header 'x-api-key: {Your API Token}' \\
--header 'Content-Type: application/json' \\
--data '{
  "background": "off_white",
  "clips": [
    {
      "avatar_name": "Mark-blueshirtfullbody-20220601",
      "avatar_style": "normal",
      "caption": true,
      "input_text": "Welcolme to movio API",
      "offset": {
        "x": 0,
        "y": 0
      },
      "scale": 1,
      "voice_name": "en-US-GuyNeural"
    },
    {
      "avatar_name": "Mark-blueshirtfullbody-20220601",
      "avatar_style": "normal",
      "caption": true,
      "input_text": "Use json to generate you own AI video now!",
      "offset": {
        "x": 0.2,
        "y": 0
      },
      "scale": 1,
      "voice_name": "en-US-GuyNeural"
    }
  ],
  "ratio": "16:9",
  "test": true,
  "version": "v1alpha"
}
'

The response will look like this :

{
	"code": 100,
	"data": {
		"video_id": "bbb89ede495247bea9389ecc42e9baeb"
	},
	"message": "Success"
}

Understanding the example

In the example above, we posted a new video generation job. Let's walk through the request json:

The version is used to select the version of our API, now the version is v1alpha.
The ratio specific the aspect ratio of the video is 16:9, in the format of {width}:{height}.
The video consists of one clip:
- The circle avatar called “bruna_18”
- bruna_18 will speak the specific text with the voice of en-US-AriaNeural.
- It contains a caption shows what the avatar speaking in the video.
- Blow the avatar is an background with "purple" as the background color.
- test field specific that the video is generate with wartermark on test envrionment.

The response json is quite simple:

code: 100 means video generate request is success.
data.video_id is the unique identifier of the video, we’ll use the video id to poll the the rendering status of the video.

The generated video

bbb89ede495247bea9389ecc42e9baeb.mp4

curl --X GET '<https://craft-api.surreal-ai.com/pacific/api/v1/video.status?video_id=bbb89ede495247bea9389ecc42e9baeb>' \\
--header 'X-Api-Key: {api-token-here}'

The server will response this if the video is still rendering:

{
	"code": 100,
	"data": {
		"id": "bbb89ede495247bea9389ecc42e9baeb",
		"status": "processing"
	},
	"message": "Success"
}

After the rendering finished, you’ll got a response like:

{
    "code": 100,
    "data":
    {
        "id": "bbb89ede495247bea9389ecc42e9baeb",
        "status": "completed"
				"video_url": "<https://s3.amazonaws.com/www.talkieselfie.xyz/aws_pacific/avatar_tmp/641b659486e24a41854810ef090c3abc/a577ca83-15a3-4869-a2ce-290d8bfbdad6.mp4?response-content-disposition=attachment%3B%20filename%3Dbbb89ede495247bea9389ecc42e9baeb.mp4&AWSAccessKeyId=AKIAR2ESI7XGYQEXSYU2&Signature=HqevbYluZqMP6PKpIdxMUde1FkI%3D&Expires=1657217774>"
    },
    "message": "Success"
}

The video_url is a public url of the generated video, download the video or save to your own storage.

<aside> 🗒️ Note: The video url will be expired in seven days, please make sure you’ve download the video or save it to somewhere safe.

</aside>

Usage

Basic

You arrange and configure an JSON and POST it to the API which will render your media and provide a file location when complete.

The Serve API base URL is: https://craft-api.surreal-ai.com/pacific/api/v1/.

Authentication

Set the X**-Api-Key** header with your Movio API key, include the header in all calls to the API that are secured with a key. The key could found on Account page in movio.la.

<aside> ❓ Don’t have an Movio account? Sign up for free now!

</aside>

Header	REQUIRED	DESCRIPTION
X-Api-Key	true	Set the X-Api-Key header with your Movio API key, include the header in all calls to the API that are secured with a key.

<aside> 💡 Movio API only avaliable for paying customers , please subscribe a plan to use movio API.

</aside>

Create Video

Render the contents of an Edit as a video, image or audio file.

Base URL: https://craft-api.surreal-ai.com/pacific/api/v1/

API Path: video.create

Request Method: POST

NAME	IN	TYPE	REQUIRED	DESCRIPTION
Body	body	https://movio-docs.notion.site/Movio-API-documentation-bb5dca96a9924109ad880130a9047edb	true	The JSON represent the whole video.

Get Video Rendering Status

Get the rendering status, temporary video url and details of a render by id.

Base URL: https://craft-api.surreal-ai.com/pacific/api/v1/

API Path: video.status

Request Method: GET

Query

NAME	IN	TYPE	REQUIRED	DESCRIPTION
id	URL parmeters	string	true	The video id in the response data of Create Video API.

API Reference

Edit

JSON FIELD	TYPE	REQUIRED	DEFAULT	DESCRIPTION
ratio	String	Mandatory	16:9	The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are:
• 16:9 - regular landscape/horizontal aspect ratio (default)
• 9:16 - vertical/portrait aspect ratio
version	string	Mandatory		The version of the API version. Use v1alpha now.
test	Boolean	Optional	false	Test videos are free and not counted towards your quota. If you create a video in the “test” mode, we will overlay a watermark over your video.
background	string	Optional	off_wite	You can use one of our stock background color

off_white
warm_white
light_pink
soft_pink
light_blue
dark_blue
soft_cyan
strong_cyan
light_orange
soft_orange Or, you can also provice a custom css color: e.g.
#FFFFFF Background can also accept an image url or video url. Supported video: mp4 Supported image: jpg, jpeg, png e.g.
https://surreal-public.oss-accelerate-overseas.aliyuncs.com/tmp/sample_earth_2s.mp4
https://surreal-public.oss-accelerate-overseas.aliyuncs.com/tmp/Business.jpg | | clips | Array of Objects | Mandatory | | The video timeline data, include all video clip info. | | clips[].input_text | String | Conditional | | Script for text-to-voice. Only one of input_text or input_audio should used. | | clips[].input_audio | String | Conditional | | Audio input for avatar to speak, the url should be an http link with public acess. Supported audio type:
mp3
wav Only one of input_text or input_audio should used. | | clips[].avatar_id | String | Mandatory | | You can use one of our avatars to generate avatar video. (See https://movio-docs.notion.site/Movio-API-documentation-bb5dca96a9924109ad880130a9047edb) | | clips[].voice_name | String | Mandatory | | The voice of the avatar, see https://movio-docs.notion.site/Movio-API-documentation-bb5dca96a9924109ad880130a9047edb for all avaliable voices. | | clips[].avatar_style | String | Optional | normal | The style of avatar. Could be one of:
circle
normal | | clips[].caption | Boolean | Optional | false | Enable the subtitle for what the avatar speaking. | | clips[].scale | Float | Optional | 1 | The scale of the avatar. | | clips[].offset | Object | | | The offset of the avatar. | | clips[].offset.x | Float | Optional | 0 | Offset an avatar on the horizontal axis (left or right), range varies from -1 to 1. Positive numbers move the asset right, negative left. For all assets except titles the distance moved is relative to the width of the viewport
i.e. an X offset of 0.5 will move the asset half the screen width to the right. | | clips[].offset.x | Float | Optional | 0 | Offset an asset on the vertical axis (up or down), range varies from -1 to 1. Positive numbers move the asset up, negative down. For all assets except titles the distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset up half the screen height. | | | | | | |

Example Json

Avatar List

Avatars

Voice List

The title is the voice name of a voice.

Chad Taylor

1625666567625.wav

ar-EG-Hoda

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/ar-SA-ZariyahNeural.mp3

ar-EG-SalmaNeural

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/ar-EG-SalmaNeural.mp3

en-AU-HayleyRUS

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/en-AU-HayleyRUS.mp3

en-AU-NatashaNeural

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/en-AU-NatashaNeural.mp3

en-GB-LibbyNeural

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/en-GB-LibbyNeural.mp3

en-GB-RyanNeural

https://surreal-public.oss-cn-beijing.aliyuncs.com/voice_preview/dubbing/azure/en-GB-RyanNeural.mp3