How to Create AI Avatar Videos Using Miraflow API

Step 1: Create a Video Generation Job

First, you'll need to create a video generation job by making a POST request to the video creation endpoint. Before creating a video, you should check whether your avatar is photo-based or video-based using the GET avatars API.

1. Check Avatar Type: First, retrieve your avatar information to determine if it's photo-based or video-based:

bash
curl -H "x-api-key: YOUR_API_KEY" https://miraflow.ai/api/avatars

Look for the isPhoto attribute in the response:

json
{
  "avatars": [
    {
      "id": "cm2yaz9j10008l0qg9npyjgs3",
      "name": "Aerin",
      "createdAt": "2024-11-01T05:37:46.194Z",
      "voiceId": "TgGcpSdbuMqeUmykspAx",
      "isPhoto": false
    },
    {
      "id": "cmdjud61z0009mr01un05uvqr",
      "name": "default avatar 1",
      "createdAt": "2025-07-26T06:00:40.679Z",
      "voiceId": "TgGcpSdbuMqeUmykspAx",
      "isPhoto": true
    }
  ]
}

2. Create Video Based on Avatar Type:

For Photo-based avatars (isPhoto: true): You can control background generation with the im2vid_full parameter. Photo-based avatars offer two distinct video generation modes:

• Face-cropped generation (im2vid_full: false): Generates videos that focus only on the avatar's face and upper body, cropping out the background. This mode is faster and more efficient, making it ideal for quick video generation when you only need the avatar speaking without background context.
• Full-background generation (im2vid_full: true): Creates videos that include the complete background environment around the avatar. This mode provides more immersive and contextually rich videos, but requires significantly more processing time due to the complexity of background generation and environmental consistency.

Generation Time Considerations: Full-background generation typically takes 2-3 times longer than face-cropped generation due to the additional computational requirements for background synthesis and environmental coherence. Choose the mode based on your content needs and time constraints.

bash
curl -X POST https://miraflow.ai/api/video/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "avatarId": "cmdjud61z0009mr01un05uvqr",
    "name": "Full background video",
    "voiceId": "female_5",
    "text": "This is a video with full background generation.",
    "im2vid_full": true
  }'

For Video-based avatars (isPhoto: false): These avatars follow their default video generation behavior and are not affected by the im2vid_full parameter. They maintain their original video characteristics and background settings as defined during avatar creation.

bash
curl -X POST https://miraflow.ai/api/video/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "avatarId": "cm2yaz9j10008l0qg9npyjgs3",
    "name": "My new video",
    "text": "TrueMedia.org detects political deepfakes in social media. Non-profit, non-partisan, and free."
  }'

If successful, you'll receive a response like this:

json
{
  "result": "success",
  "jobId": "cm73nm9oj0008oc01jea6d2qi"
}

Step 2: Check Job Status

Using the jobId from the previous step, you can check the status of your video generation job:

bash
curl -H "x-api-key: YOUR_API_KEY" https://miraflow.ai/api/video/{jobId}/status 

The response will look like one of these:

json
// When the job is in progress
{
  "result": "success",
  "status": "inference_working",
  "progress": "45%"
}

// When the job is complete
{
  "result": "success",
  "status": "inference_complete",
  "videoId": "cm73nm9oj0009oc01jea6d2qj"
}

Possible Status Values:

Step 3: Download the Video

Once the status is inference_complete, you can use the videoId from the status response (not the jobId from Step 1) to download your video:

bash
curl -H "x-api-key: YOUR_API_KEY" https://miraflow.ai/api/video/{videoId}/download --output video.mp4

Error Handling

The API uses standard HTTP status codes:

• 200: Success
• 400: Bad request (missing parameters)
• 401: Invalid or missing API key
• 404: Resource not found
• 500: Internal server error

Error responses will include a message explaining what went wrong:

json
{
  "result": "failure",
  "error": "Error message here"
}

Best Practices

1. Poll Status Responsibly: When checking job status, implement exponential backoff with a reasonable interval (e.g., starting at 5 seconds and increasing).
2. Handle Errors Gracefully: Always check for error responses and implement appropriate retry logic.
3. Store Video IDs: Once a video is generated, store its ID if you plan to access it again later.

Complete Example

Here's a complete Python script demonstrating the entire process:

python
import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://miraflow.ai/api"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_video(avatar_id, speech_id, name, im2vid_full=False):
    response = requests.post(
        f"{BASE_URL}/video/create",
        headers=HEADERS,
        json={
            "avatarId": avatar_id,
            "speechId": speech_id,
            "name": name,
            "im2vid_full": im2vid_full
        }
    )
    return response.json()["jobId"]

def check_status(job_id):
    response = requests.get(
        f"{BASE_URL}/video/{job_id}/status",
        headers=HEADERS
    )
    return response.json()

def download_video(video_id, output_path):
    response = requests.get(
        f"{BASE_URL}/video/{video_id}/download",
        headers=HEADERS,
        stream=True
    )
    with open(output_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)

# Create a video
job_id = create_video("avatar_id", "speech_id", "Test Video", im2vid_full=False)

# Poll for completion
while True:
    status = check_status(job_id)
    if status["status"] == "inference_complete":
        video_id = status["videoId"]
        break
    elif status["status"] in ["inference_failed", "inference_error"]:
        raise Exception(f"Video generation failed: {status}")
    print(f"Progress: {status.get('progress', '0%')}")
    time.sleep(5)

# Download the video
download_video(video_id, "output.mp4")

API Reference

Below is the complete reference for all available API endpoints. All endpoints require authentication using your API key in the request header. For the most up-to-date documentation, visit our API Documentation.

bash
curl -H "x-api-key: YOUR_API_KEY" https://miraflow.ai/api/avatars

List Avatars

Lists available avatars, including stock avatars and those created by your account.

bash
GET /api/avatars

json
{
  "avatars": [
    {
      "id": "cm2yaz9j10008l0qg9npyjgs3",
      "name": "Aerin",
      "createdAt": "2024-11-01T05:37:46.194Z",
      "voiceId": "TgGcpSdbuMqeUmykspAx",
      "isPhoto": false
    },
    {
      "id": "cmdjud61z0009mr01un05uvqr",
      "name": "default avatar 1",
      "createdAt": "2025-07-26T06:00:40.679Z",
      "voiceId": "TgGcpSdbuMqeUmykspAx",
      "isPhoto": true
    }
  ]
}

Avatar Types:

• Photo-based avatars (isPhoto: true):Support both full-background and face-cropped video generation. Full-background videos generally take longer to generate.


• Video-based avatars (isPhoto: false):Follow their default video generation behavior and are not affected by the im2vid_full parameter.

List Voices

Lists available voices, including stock voices and those created by your account.

bash
GET /api/voices

json
{
  "voices": [
    {
      "id": "cm5n372yq0003vow86ukx8zfe",
      "name": "Belinda - Curious and Soft",
      "createdAt": "2025-01-07T23:13:33.103Z"
    }
  ]
}

List Videos

Lists all completed videos.

bash
GET /api/videos

json
{
  "videos": [
    {
      "id": "cm5n3bnpa000avow8t6p5yc4l",
      "name": "Test video",
      "sourceAvatarId": "cm2yaz9j10008l0qg9npyjgs3",
      "createdAt": "2025-01-07T23:17:06.601Z"
    }
  ]
}

Get Video Metadata

Fetches metadata for a single completed video.

bash
GET /api/video/{id}

json
{
  "id": "cm5n3bnpa000avow8t6p5yc4l",
  "name": "Test video",
  "sourceAvatarId": "cm2yaz9j10008l0qg9npyjgs3",
  "createdAt": "2025-01-07T23:17:06.601Z",
  "downloadUrl": "https://miraflow-media.s3.us-west-2.amazonaws.com/cm5n3bnpa000avow8t6p5yc4l.mp4"
}

Create Video

Starts a new video generation job. You can either create a speech using a voice and script, or use an existing speech ID.

bash
POST /api/video/create

Option 1: Create with voice and text:

json
{
  "avatarId": "cm2yaz9j10008l0qg9npyjgs3",
  "name": "My new video",
  "voiceId": "cm1lgilny0005m2lnvv3vgtgv",
  "text": "This is the text of the script to be generated in the specified voice.",
  "im2vid_full": false
}

Option 2: Create with existing speech:

json
{
  "avatarId": "cmdjud61z0009mr01un05uvqr",
  "name": "My new video",
  "speechId": "cm5n372yq0003vow86ukx8zfe",
  "im2vid_full": true
}

im2vid_full Parameter:

• For photo-based avatars (isPhoto: true):Controls whether the generated video includes the full background or is face-cropped.


• For video-based avatars (isPhoto: false):This parameter is ignored as they follow their default video generation behavior.


• Parameter Values:
• im2vid_full: true → Full background video generation (slower, more immersive)
• im2vid_full: false → Face-cropped video generation (faster, focused content)

Success Response:

json
{
  "result": "success",
  "jobId": "cm42ab3ou0008aggajj0jy5e2"
}

Check Video Status

Checks the status of a video generation job.

bash
GET /api/video/{jobId}/status

json
{
  "result": "success",
  "status": "inference_working",
  "progress": "45%"
}

Download Video

Downloads a completed video file.

bash
GET /api/video/{id}/download

Returns the video file with Content-Type: video/mp4

Conclusion

The Miraflow API provides a straightforward way to generate AI videos programmatically. By following this guide and implementing proper error handling and status polling, you can easily integrate video generation into your applications.

For more information and detailed API documentation, visit our API Referencepage.