Name: Stable Diffusion – Text-to-Video Animation | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-image-animation-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Text-to-Video Animation API – Smooth Prompt Interpolation (Stable Diffusion)

## Overview
The Text-to-Video Animation API allows you to create seamless, AI-generated animations by interpolating between two text prompts using Stable Diffusion. It generates a series of frames that smoothly transition from one prompt to another and can deliver the result as a GIF or MP4 video.

## Features
- Interpolate between two prompts to create smooth transitions
- Adjustable guidance scale to control Video adherence to the prompt
- Options for GIF or MP4 output format
- Frame interpolation with FILM for smooth in-between frames
- Adjustable number of frames and frame rate for full control over animation speed

## Use Cases
1. Storyboarding and concept art: Quickly visualize transitions between story elements.  
2. Animated social media content: Generate short, unique, AI-driven animations to captivate audiences.  
3. Generative art installations: Craft evolving artwork that transitions between multiple prompts.  
4. Educational content: Demonstrate progressive transformations of Video, aiding in visual explanations.  
5. Marketing promotions: Stand out with AI-crafted animations for branding and campaigns.

## Examples

### Example of a Generated Animation
Below is a sample output URL provided in the OpenAPI schema for a successful prediction:

![Sample AI-generated animation from the prompt transition](https://replicate.delivery/mgxm/56df19d7-3776-4119-a0f9-d278b26a4a8a/output.mp4)

It shows an example video transitioning from one prompt describing a desert scene with a black monolith to another describing a futuristic room with a monolith.

### Example Input Prompts
- Prompt Start:
  ```
  tall rectangular black monolith, monkeys in the desert looking at a large tall monolith, a detailed matte painting by Wes Anderson, behance, light and space, reimagined by industrial light and magic, matte painting, criterion collection
  ```
- Prompt End:
  ```
  tall rectangular black monolith, a white room in the future with a bed, victorian details and a tall black monolith, a detailed matte painting by Wes Anderson, behance, light and space, reimagined by industrial light and magic, matte painting, criterion collection
  ```

These two prompts are seamlessly interpolated to create the final animation.

## Pricing
- 1 API unit equals 1 Video processed (an entire animation request consumes units equal to the number of frames generated).
- Checking prediction status using GET /api/v1/magicapi/ai-image-animation-generator/predictions/{id} is free and does not count toward API usage.
- Various pricing tiers are available depending on your monthly usage volume.

## API Documentation

### Base URL
All requests should be made to:
```
https://prod.api.market/api/v1/magicapi/ai-image-animation-generator
```

### Authentication
Include your API key in the header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API uses asynchronous prediction requests. The typical workflow is:
1. POST a prediction request to the /predictions endpoint.
2. Receive a prediction ID in the response with a status of `starting`.
3. Poll the GET /predictions/{id} endpoint to monitor the status.
4. Once the status changes to `succeeded`, retrieve the output (GIF or MP4).
5. If the status becomes `failed`, handle the error accordingly.

Recommended polling strategy:
- Check every 1 second until completion or until 600 seconds (10 minutes) have elapsed.
- If not completed within 600 seconds, consider it a timeout and handle accordingly.

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• Endpoint:  
  ```
  /api/v1/magicapi/ai-image-animation-generator/predictions
  ```  
• Description: Submits the request to create a new animation.  

Example Request (JSON):
```json
{
  "input": {
    "prompt_start": "tall rectangular black monolith, monkeys in the desert looking at a large tall monolith...",
    "prompt_end": "tall rectangular black monolith, a white room in the future with a bed...",
    "gif_ping_pong": true,
    "output_format": "mp4",
    "guidance_scale": 7.5,
    "prompt_strength": 0.9,
    "film_interpolation": true,
    "num_inference_steps": 50,
    "num_animation_frames": 25,
    "gif_frames_per_second": 20,
    "num_interpolation_steps": 5,
    "width": 512,
    "height": 512
  }
}
```

Example Curl:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "prompt_start": "tall rectangular black monolith, monkeys in the desert...",
      "prompt_end": "tall rectangular black monolith, a white room in the future...",
      "gif_ping_pong": true,
      "output_format": "mp4"
    }
  }'
```

Possible Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ca1f5e306e5721e19c473e0d094e6603f0456fe759c10715fcd6c1b79242d4a5",
  "status": "starting",
  "created_at": "2025-04-21T10:44:09.635Z"
}
```

#### 2. Get Prediction Status
• Method: GET  
• Endpoint:
  ```
  /api/v1/magicapi/ai-image-animation-generator/predictions/{id}
  ```  
• Description: Check the status of a submitted prediction.  

Example Curl:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Possible Response (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://replicate.delivery/mgxm/56df19d7-3776-4119-a0f9-d278b26a4a8a/output.mp4"
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

### Status Codes
- 200 OK: Request was successful.  
- 201 Created: New prediction resource created.  
- 400 Bad Request: Invalid input or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key, but insufficient permissions for the request.  
- 404 Not Found: The specified resource could not be found.  
- 429 Too Many Requests: Rate limit exceeded.  
- 500 Internal Server Error: An error occurred on the server side.  
- 503 Service Unavailable: The service is temporarily unavailable, try again later.

## Rate Limits
- The API enforces a rate limit to ensure fair usage.
- If you exceed the limit (HTTP 429), reduce request frequency and implement retry logic with exponential backoff.

## Error Handling
Error responses will generally have a JSON structure with an “error” object. For example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt_start' is required",
    "status": 400
  }
}
```
Best practices:
- Check the HTTP status code first.
- Inspect the error message for hints on how to correct or handle the issue.
- Implement retries for 429 or other transient errors.

## Implementation Guide

### JavaScript Example
```javascript
// Replace ${productInfo.slug} with ai-image-animation-generator
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({ input: inputData })
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.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 response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

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

    const prediction = await response.json();

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

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

    await delay(POLL_INTERVAL);
  }

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

// Usage example:
createAndWaitForPrediction({
  prompt_start: "First prompt...",
  prompt_end: "Second prompt..."
}).then(output => {
  console.log("Animation output URLs:", output);
}).catch(err => {
  console.error(err);
});
```

### Python Example
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator"

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={"input": input_data})

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

    prediction = response.json()
    prediction_id = prediction.get("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
    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

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

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

        prediction = response.json()
        status = prediction.get("status")

        if status == "succeeded":
            return prediction.get("output")
        if 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")

# Usage example:
output_urls = create_and_wait_for_prediction({
    "prompt_start": "First prompt...",
    "prompt_end": "Second prompt..."
})
print("Animation output URLs:", output_urls)
```

### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "prompt_start": "First prompt...",
      "prompt_end": "Second prompt..."
    }
  }'

# Example response:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Check the prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-animation-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Reduce the number of frames for faster generation and fewer total API units consumed.  
- Use minimal inference steps to speed up generation, but be mindful that fewer steps can lower output quality.  
- Parallelize requests carefully to avoid hitting rate limits, and implement exponential backoff for retries.

## FAQ
1. **Why is my animation “jumping”?**  
   Raise or lower the `prompt_strength` to adjust how closely frames adhere to the text prompt. Lower values often produce smoother transitions.  

2. **Can I reverse the animation automatically?**  
   Yes, enable `gif_ping_pong` when generating GIF outputs to have it loop forward and backward.  

3. **What if my animation fails to generate?**  
   Check the error message returned with the `failed` status and adjust your parameters accordingly (e.g., reduce resolution or frames).  

4. **How can I control the output format?**  
   Set `output_format` to `"gif"` or `"mp4"` in your request body.

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

Generate smooth AI video animations from two text prompts. Outputs GIF or MP4 video. From $0.05/call. Try it free on API.market.

Stable Diffusion – Text-to-Video Animation | $0.05/call | API.market