Name: Hunyuan Video2Video – AI Motion Synthesis | Free · $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-text-to-video-generation-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 Realistic Text-to-Video Generator API (Hunyuan-Video2Video)

## Overview
The Realistic Text-to-Video Generator API (Hunyuan-Video2Video) is a cutting-edge solution for transforming text prompts and an existing input video into high-fidelity, lifelike motion sequences. Whether you're creating cinematic scenes or short clips, this API leverages sophisticated AI to craft videos that closely follow your descriptive prompts, all while preserving smooth motion and consistent visual quality.

## Features
- Generate lifelike video sequences from text prompts and an input video.  
- Control the output video’s resolution, frame rate, and quality to suit various production requirements.  
- Fine-tune motion characteristics via parameters such as flow shift and denoise strength.  
- Maintain or alter aspect ratios to fit a wide range of creative scenarios.  
- Asynchronous processing supports concurrent requests while ensuring high throughput.

## Use Cases
1. **Film Pre-Visualization:** Directors and storyboard artists can quickly generate mock-up scenes from text prompts to visualize how live-action shots may look.  
2. **Social Media Content:** Influencers and marketers can transform straightforward text concepts into animated content for more dynamic storytelling.  
3. **Educational Videos:** Novel ways to illustrate scientific or historical concepts by generating unique animated scenes that match a written description.  
4. **Advertising and Branding:** Marketing teams can create tailored video snippets, matching brand guidelines and style prompts to existing footage.  
5. **Prototyping & Rapid Iteration:** Designers and developers can iterate on video concepts rapidly, saving valuable time and resources in the creative process.

## Visual Examples
Below are example links that demonstrate input and output videos. These were provided in the OpenAPI schema. You can view them to understand how your final output might appear compared to the original input:

### Input Video
This is an example input video provided in the schema, showing a cat walking on the grass in a realistic style.

![Example input video showing a cat walking on the grass in a realistic style](https://replicate.delivery/pbxt/M5n5MuDgBxhSERj6PvHgz4BJcOUdHc9o1ZBXz454GoGP5DrR/2024-12-03-18%3A25%3A47_seed47039_A%20cat%20walks%20on%20the%20grass%2C%20realistic%20style..mp4)

### Output Video
Below is an example output video from a completed prediction. It’s an AI-generated scene reflecting the requested prompt in a high-quality, fluid animation.

![Example output video showing an AI-generated realistic scene](https://replicate.delivery/xezq/fPeeEckco8DfnQ8zUUpbawLy0ezXMEP5if95pXKyAYFKOf58JA/HunhuyanVideo_00001.mp4)

## Pricing
• 1 API unit equals 1 video processed via a POST request.  
• Checking prediction status (GET /api/v1/magicapi/text-to-video-generation-api/predictions/{id}) does not consume API units.  
• Flexible pricing tiers are available based on usage volume. Contact us to discuss options that best fit your needs.

## API Documentation

### Base URL
All requests to this API should be sent to:

```
https://prod.api.market/api/v1/magicapi/text-to-video-generation-api
```

### Authentication
Include your API key in every request using the following header:

```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
Predictions are processed asynchronously to provide efficient handling of longer-running video operations. Here is the typical request flow:

1. Send a POST request to create a prediction.  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint with this prediction ID to check status.  
4. Continue polling until the status is "succeeded" (or "failed").  

Processing times depend on video length, requested resolution, and other parameters. Best practices for polling:
- Check status every 1 second.  
- Use a maximum timeout of 600 seconds (10 minutes).  
- If status is "starting" or "processing," keep polling.  
- Once "succeeded," retrieve the final output URL.  
- If "failed," handle the error gracefully.

---

### Endpoints

#### 1. Create a Prediction  
• **Endpoint**:  
  POST /api/v1/magicapi/text-to-video-generation-api/predictions  

• **Summary**:  
  Request a new AI-generated video transformation, returning a unique prediction ID.

• **Request Body** (JSON):
```json
{
  "version": "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
  "input": {
    "video": "https://your-video-url.mp4",
    "prompt": "A scenic mountain landscape with flowing rivers, cinematic style",
    "width": 768,
    "height": 768,
    "steps": 30,
    "crf": 19,
    "flow_shift": 9,
    "force_rate": 0,
    "force_size": "Disabled",
    "frame_rate": 24,
    "custom_width": 512,
    "custom_height": 512,
    "frame_load_cap": 101,
    "guidance_scale": 6,
    "keep_proportion": true,
    "denoise_strength": 0.85,
    "select_every_nth": 1,
    "skip_first_frames": 0
  }
}
```

• **Response (JSON)**:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
  "status": "starting",
  "created_at": "2025-04-22T22:38:38.799Z"
}
```

• **cURL Example**:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
    "input": {
      "video": "https://example.com/your-input-video.mp4",
      "prompt": "A scenic mountain landscape with flowing rivers, cinematic style",
      "width": 768,
      "height": 768
    }
  }'
```

---

#### 2. Get Prediction Status and Results  
• **Endpoint**:  
  GET /api/v1/magicapi/text-to-video-generation-api/predictions/{id}  

• **Summary**:  
  Poll this endpoint to retrieve the status of a previously requested prediction and, when complete, the output video.

• **Response (JSON)**:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://my-generated-video-2025.mp4",
  "error": null,
  "created_at": "2025-04-22T22:38:38.799Z",
  "started_at": "2025-04-22T22:38:39.202Z",
  "completed_at": "2025-04-22T22:39:08.157Z"
}
```

• **cURL Example**:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api/predictions/{id}" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

---

## Status Codes
Below is a list of HTTP status codes you may encounter and how to handle them:

- **200 OK**: Request was successful (used mainly for GET requests).  
- **201 Created**: Resource created successfully (used for POST /predictions).  
- **400 Bad Request**: Your request was malformed or invalid (check parameters).  
- **401 Unauthorized**: Missing or incorrect API key (ensure header is set).  
- **403 Forbidden**: The API key is valid but lacks necessary permissions.  
- **404 Not Found**: The requested resource or prediction ID does not exist.  
- **429 Too Many Requests**: Rate limit exceeded. Implement retries with backoff.  
- **500 Internal Server Error**: A server-side error occurred. Retry or contact support.  
- **503 Service Unavailable**: The service is temporarily overloaded or under maintenance. Retry after a short delay.

## Rate Limits
The API imposes certain throttles to ensure stable service for all users. If you receive a 429 Too Many Requests status:
1. Pause further requests for a short period.  
2. Implement an exponential backoff strategy.  
3. Resume requests when the rate limit window resets.

## Error Handling
When an error occurs, the API typically responds with a descriptive JSON payload. For example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'video' is required",
    "status": 400
  }
}
```

Best practices:
- Check the HTTP status code and the "error" object for details.  
- Log the details for debugging.  
- For transient errors (like 5xx or 429), implement retries with exponential backoff.  
- For client errors (4xx), correct the request parameters before retrying.

## Implementation Guide

### Example Code

Below are examples in JavaScript, Python, and cURL illustrating how to integrate the asynchronous prediction flow, handle authentication, and manage polling with timeouts.

#### JavaScript (Node.js) Example

```javascript
// Replace with your actual API key
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const createResponse = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
        input: inputData
      })
    });

    if (!createResponse.ok) {
      throw new Error(`API error: ${createResponse.status} ${createResponse.statusText}`);
    }

    const prediction = await createResponse.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const statusResponse = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!statusResponse.ok) {
      throw new Error(`API error: ${statusResponse.status} ${statusResponse.statusText}`);
    }

    const predictionStatus = await statusResponse.json();

    if (predictionStatus.status === "succeeded") {
      return predictionStatus.output;
    }

    if (predictionStatus.status === "failed") {
      throw new Error(`Prediction failed: ${predictionStatus.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

// Example usage
(async () => {
  try {
    const inputData = {
      video: "https://example.com/your-input-video.mp4",
      prompt: "A breathtaking time-lapse of blooming flowers, hyperrealistic style"
    };
    const outputUrl = await createAndWaitForPrediction(inputData);
    console.log("Your generated video is available at:", outputUrl);
  } catch (err) {
    console.error("Prediction error:", err);
  }
})();
```

#### Python Example

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
            "input": input_data
        }
    )
    
    if response.status_code not in [200, 201]:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-magicapi-key": API_KEY}
        )

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")

# Example usage
if __name__ == "__main__":
    try:
        input_data = {
            "video": "https://example.com/your-input-video.mp4",
            "prompt": "A futuristic city skyline with glowing neon signs"
        }
        result_url = create_and_wait_for_prediction(input_data)
        print("Generated Video URL:", result_url)
    except Exception as e:
        print("Error:", str(e))
```

#### cURL Example

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api/predictions" \
     -H "Content-Type: application/json" \
     -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
     -d '{
       "version": "d550f226f28b1030c2fedd2947f39f19b4b0233b50364904538caaf037fb18d3",
       "input": {
         "video": "https://example.com/your-input-video.mp4",
         "prompt": "A magical forest scene with sparkling lights"
       }
     }'

# You receive a JSON response with a 'status' and an 'id':
# {"id": "abcd1234", "status": "starting", ...}

# Step 2: Poll for status
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generation-api/predictions/abcd1234" \
     -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Continue polling until "status" becomes "succeeded" or "failed".
```

### Performance Optimization
- Use lower image/video resolutions (width/height) to reduce inference time.  
- If possible, reduce the number of denoising steps.  
- For real-time or near real-time requirements, design your system to handle concurrency with efficient queue management.

## FAQ
1. **How long does it take to generate a video?**  
   It depends on factors like video length, resolution, and the selected denoising steps. Most requests finish in under a few minutes.

2. **What if I need to process very large or high-resolution videos?**  
   You can configure custom_height, custom_width, and force_size to match your needs, but be mindful of processing time and cost.

3. **Can I maintain the original aspect ratio?**  
   Yes, set keep_proportion to true, and the API will automatically adjust the width or height to keep the aspect ratio consistent.

4. **How do I retrieve the final video URL?**  
   Poll the GET /predictions/{id} endpoint until the status is succeeded. The URL will be in the output field.

5. **What if my prediction fails?**  
   The API returns an error message in the response JSON. Adjust your prompt or inputs and try again, or contact support if the issue persists.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Create lifelike videos from text and an input video. Fine-tune motion, resolution, and frame rate. Free 10 calls/mo, from $5/mo. Start free on API.market.

Hunyuan Video2Video – AI Motion Synthesis | Free · $5/mo | API.market

🎥 Realistic Text-to-Video Generator API (Hunyuan-Video2Video)

FREE

MagicAPI

PAYG

START

ULTRA

ELITE

MEGA

GIGA

BULK

Create high-quality, lifelike videos from text prompts with fast, state-of-the-art AI motion synthesis.