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.

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:

{
  "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:

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

The response will look like one of these:

// 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:

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:

{
  "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:

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):
    response = requests.post(
        f"{BASE_URL}/video/create",
        headers=HEADERS,
        json={
            "avatarId": avatar_id,
            "speechId": speech_id,
            "name": name
        }
    )
    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")

# 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.

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.

GET /api/avatars

{
  "avatars": [
    {
      "id": "cm2yaz9j10008l0qg9npyjgs3",
      "name": "Aerin",
      "createdAt": "2024-11-01T05:37:46.194Z"
    }
  ]
}

List Voices

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

GET /api/voices

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

List Videos

Lists all completed videos.

GET /api/videos

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

GET /api/video/{id}

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

POST /api/video/create

Option 1: Create with voice and text:

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

Option 2: Create with existing speech:

{
  "avatarId": "cm2yaz9j10008l0qg9npyjgs3",
  "name": "My new video",
  "speechId": "cm5n372yq0003vow86ukx8zfe"
}

Success Response:

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

Check Video Status

Checks the status of a video generation job.

GET /api/video/{jobId}/status

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

Download Video

Downloads a completed video file.

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 Reference page.