Name: Pyramid Flow – AI Video Generation | $0.1/call | API.market
Brand: magicapi
SKU: api-magicapi-text-video-image-video-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Fast Text-to-Video & Image-to-Video API (Pyramid Flow)

## Overview
The Fast Text-to-Video & Image-to-Video API (Pyramid Flow) allows you to generate high-quality AI-generated videos from text prompts or source images. Leveraging advanced autoregressive video generation, it supports flexible configurations such as custom duration, frames per second, and guidance scales. This makes it a powerful tool for rapid prototyping, creative content generation, and visual storytelling.

## Features
- Generate short or longer videos (1–10 seconds) with flexible duration settings.  
- Produce smooth, high-fidelity clips at 8 or 24 frames per second.  
- Optionally start from an image (for image-to-video transformations) or just a text prompt (for text-to-video generation).  
- Adjustable guidance scale parameters for tuning creative output.  
- Asynchronous processing to handle complex tasks without blocking your application.  

## Use Cases
1. Video Teaser Creation: Quickly turn text scenarios or scripts into short video clips for marketing or social media teasers.  
2. Concept Art for Film/Animation: Transform concept images or rough sketches into short animated sequences for storyboarding or pitch decks.  
3. Education and E-Learning: Generate illustrative or scenario-based videos from text prompts to aid in interactive lesson plans.  
4. Rapid Prototyping for Advertising: Test multiple creative directions by simply adjusting the text prompt or image reference.  
5. Artistic Exploration: Experiment with abstract or imaginative prompts to quickly see a visual interpretation brought to life.

## Visual Examples

Below are some example inputs and outputs derived from the schema:

### Input Image Example
This example image might be used as a starting point for image-to-video generation:
![Sample input image for image-to-video generation](https://blog.api.market/wp-content/uploads/2025/04/Screenshot-2025-04-24-at-12.49.59 AM.png)

### Output Video Link Example
Although a static image preview is not available for videos, here is a sample output link (from the schema’s “output” field in example responses):  

![Example Output Video a video generated using text prompt](https://replicate.delivery/yhqm/5fhDu5VhX21zBK3oCphPd2SvQ1px4wvLgF8Ughg5U1EjlwyJA/output_video.mp4)

Prompt used in the example:  
"A gripping movie trailer showcasing a young female astronaut in a iridescent spacesuit, sporting a red wool knitted space helmet. She explores a bioluminescent alien forest under twin moons, filmed in vivid IMAX quality. Retro sci-fi aesthetic, lens flares"

## Pricing
• 1 API unit equals 1 image processed (in this case, each video request is considered 1 unit).  
• GET requests to check prediction status (GET /api/v1/magicapi/text-video-image-video-generator/predictions/{id}) are free and do not count toward API unit usage.  
• Different pricing tiers are available based on usage volume.

## API Documentation

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

### Authentication
Include your API key in the request header:

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

### Asynchronous Processing
This API uses asynchronous processing for generating videos:

1. Submit your prediction request to the POST endpoint.  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint with the prediction ID to check status.  
4. Continue polling until the status is "succeeded" or an error/timeout occurs.  

Processing time varies depending on your input parameters.

Recommended polling approach:  
- Poll every 1 second.  
- Stop polling if the status is "succeeded", "failed", or if 600 seconds have elapsed.  

### Endpoints

#### 1. Create a Prediction
• Path:  
  POST /api/v1/magicapi/text-video-image-video-generator/predictions  
• Description:  
  Create a new prediction to generate an AI video.  
• Request Body (JSON):

```json
{
  "version": "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
  "input": {
    "prompt": "Your text prompt here",
    "duration": 5,
    "guidance_scale": 9,
    "frames_per_second": 24,
    "video_guidance_scale": 5,
    "image": "https://example.com/image.jpg"
  }
}
```
- prompt (string): Required text prompt for video generation.  
- image (string, optional): URL of the source image (for image-to-video).  
- duration (integer): Duration of the video in seconds (1-10).  
- frames_per_second (integer): The frame rate (8 or 24) for canonical mode.  
- guidance_scale (number): Main guidance scale value for text-driven generation.  
- video_guidance_scale (number): Scale for video guidance for stable motion.

• Example cURL:

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-video-image-video-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
    "input": {
      "prompt": "A gripping movie trailer showcasing a young female astronaut in an iridescent spacesuit...",
      "duration": 5,
      "frames_per_second": 24,
      "guidance_scale": 9
    }
  }'
```

• Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
  "status": "starting",
  "created_at": "2025-04-22T22:38:40.277Z"
}
```

#### 2. Get Prediction Status
• Path:  
  GET /api/v1/magicapi/text-video-image-video-generator/predictions/{id}  
• Description:  
  Retrieve the current status and (once complete) the resulting video URL.  
• Example cURL:

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

• Response (200 OK) if succeeded:

```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/yhqm/5fhDu5VhX21zBK3oCphPd2SvQ1px4wvLgF8Ughg5U1EjlwyJA/output_video.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: A new prediction was successfully created.  
- 400 Bad Request: Invalid or malformed request. Check input parameters.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key but insufficient permissions for the requested action.  
- 404 Not Found: The requested resource or prediction ID was not found.  
- 429 Too Many Requests: You have hit a rate limit; retry after a short backoff.  
- 500 Internal Server Error: A server-side error occurred.  
- 503 Service Unavailable: The service is temporarily unavailable, likely due to high load.

## Rate Limits
Each account is subject to certain request limits based on the plan or tier chosen. If you receive a 429 (Too Many Requests) status, consider upgrading your plan or optimizing your request strategy.

## Error Handling
When the API encounters an error, it will return a JSON response with a description of what went wrong. Example:

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

Best practices:  
- Check the HTTP status code.  
- Inspect the "code" and "message" fields in the JSON payload for clarification.  
- Implement retry logic for transient errors like 429 or 503.  
- For validation errors (400), correct the request data before retrying.

## Implementation Guide

### Example Code

Below are sample implementations demonstrating how to use the API, handle asynchronous prediction processing, and manage timeouts.

#### JavaScript (using fetch and async/await)

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-video-image-video-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({
        version: "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
        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");
}

// Example usage:
// (async () => {
//   const videoOutputUrl = await createAndWaitForPrediction({
//     prompt: "A short animation of a rainbow swirling around a mountain peak",
//     duration: 3
//   });
//   console.log("Video URL:", videoOutputUrl);
// })();
```

#### Python (using requests and time.sleep)

```python
import requests
import time

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

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }

    payload = {
        "version": "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", json=payload, headers=headers)
    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  # seconds
    POLL_INTERVAL = 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()

        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:
# video_url = create_and_wait_for_prediction({
#   "prompt": "A mesmerizing galaxy swirling among the stars",
#   "duration": 5,
#   "frames_per_second": 24
# })
# print("Video URL:", video_url)
```

#### cURL

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/text-video-image-video-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "8e221e66498a52bb3a928a4b49d85379c99ca60fec41511265deec35d547c1fb",
    "input": {
      "prompt": "A futuristic cityscape at sunrise",
      "duration": 3
    }
  }'

# Example response:
# {
#   "id": "abcd1234",
#   "status": "starting",
#   "created_at": "2025-04-22T22:38:40.277Z"
# }

# Step 2: Poll for status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/text-video-image-video-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Check status in the response until it shows "succeeded" or "failed".
```

### Performance Optimization
- Use smaller durations or lower frames per second for faster generation.  
- Tune your prompts carefully—overly complex prompts may take longer or lead to less predictable outcomes.  
- Implement proper caching or store final results if you plan to retrieve the same output multiple times.

## FAQ
1. What is the maximum video duration allowed?  
   The API supports 1–3 seconds for canonical mode, and up to 10 seconds for non-canonical mode.  

2. Can I generate videos from an image plus a text prompt?  
   Yes, providing both an image URL and a text prompt is supported.  

3. How often should I poll for the prediction status?  
   Poll once per second to avoid hitting rate limits.  

4. How do I reduce costs?  
   Optimize your requests by using shorter videos and fewer frames per second. Bulk pricing tiers are also available.  

5. Is there a limit on the size of the input image?  
   The image must be a valid URL accessible by the API. Larger images may impact processing time.

## 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 high-quality AI videos from text or images in seconds. Supports up to 10s duration at 24 FPS. From $0.1/call. Try it free on API.market.

Pyramid Flow – AI Video Generation | $0.1/call | API.market

🎬 Fast Text-to-Video & Image-to-Video API (Pyramid Flow)

PAYG

MagicAPI

Generate high-quality AI videos from text or images in seconds with Pyramid Flow’s advanced autoregressive video generation—perfect for content creation and rap