Name: Video Aspect Ratio Changer API (Luma Reframe Video)
Brand: magicapi
SKU: api-magicapi-change-video-aspect-ratio-luma-reframe-video
Availability: InStock
Author: API Market

Shashank Agarwal

# 📐 Aspect Ratio Changer API - 720p Reframe (Luma Reframe Video)

## Overview
Luma Reframe Video changes the aspect ratio of a video. Send a video and pick a target aspect ratio such as `9:16` or `1:1`, and the model generates a reframed version of the clip. Outputs are 720p. The input field descriptions give a maximum input length of 10 seconds.

You can optionally guide the result with a `prompt`, and control where the source sits in the new frame with the grid position and crop bound fields.

## Features
- **Aspect ratio change**: `aspect_ratio` of `1:1`, `3:4`, `4:3`, `9:16`, `16:9` (default), `9:21` or `21:9`.
- **720p output**: reframed videos are returned at 720p.
- **Prompt guidance**: an optional `prompt` guides the reframing generation.
- **Placement control**: `grid_position_x` and `grid_position_y` set where the source sits within the output frame, in pixels.
- **Crop bounds**: `x_start`, `x_end`, `y_start` and `y_end` (pixels) set the area the source occupies in the output frame; the distance between start and end sets the resized width or height of your content.

## Use Cases
1. **Vertical versions for social apps**: turn a `16:9` clip into `9:16` for short-form vertical feeds.
2. **Square posts**: produce `1:1` versions of a video for feeds that favor square media.
3. **Widescreen versions**: turn vertical footage into `16:9` or `21:9` for web players and presentations.
4. **Ad formats**: create several aspect ratios of one clip for different ad placements.

## Visual Examples

The example reframed a short clip (a woman in a yellow hooded raincoat on a rainy street at night under a neon sign) to `9:16`. Request input:

```json
{
  "video_url": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "aspect_ratio": "9:16"
}
```

- Input video: [Watch the input video](https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4)
- Output video (9:16): [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/reframe-video-output-api-market.mp4)

The example used `video_url`, which still works but is marked deprecated in the model schema. For new integrations, send the video URL in `video` instead.

## Pricing
- Pay As You Go (PAYG) pricing: you only pay for what you use.
- Price: $0.075 per API unit.
- 1 API unit = 1 second of output video, rounded up to a whole second (minimum 1 unit per request).
- Worked example: reframing a 5 second clip returns a 5 second video, which is 5 units x $0.075 = $0.375. A 10 second clip is 10 units = $0.75.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status (GET /api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video/predictions/{id}) are free and don't count toward API unit usage.
- No monthly subscription fee.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video`

### Authentication
Include your api.market API key in the `x-api-market-key` header of every request:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API is asynchronous:

1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the prediction was accepted; it is not an error.
2. Poll GET `/predictions/{id}` (about once per second) while `status` is `starting` or `processing`.
3. Stop when `status` is `succeeded` (read the result from `output`), `failed` (see `error`) or `canceled`.

Video generation can take a while. The code samples below poll once per second and give up after 600 seconds (10 minutes); raise the timeout if your requests take longer.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7a27619ccb64e4f1942e9a53e503142be08d505587313afa1da037b631a6760e",
    "input": {
      "video_url": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
      "aspect_ratio": "9:16"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "7a27619ccb64e4f1942e9a53e503142be08d505587313afa1da037b631a6760e",
  "status": "starting",
  "created_at": "2026-10-13T10:33:40.967Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/reframe-video-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-13T10:33:40.967Z",
  "started_at": "2026-10-13T10:33:41.512Z",
  "completed_at": "2026-10-13T10:34:02.104Z"
}
```

### Input Parameters

| Name | Type | Default | Allowed values | Required | Description |
|------|------|---------|----------------|----------|-------------|
| `video` | string (URI) |  | Video URL | No | The video to reframe. Maximum video duration is 10 seconds. Use this field (or the deprecated `video_url`) to send your video. |
| `video_url` | string |  | Video URL | No | Deprecated. URL of the video to reframe. Maximum video duration is 10 seconds. Prefer `video`. |
| `aspect_ratio` | string | `16:9` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `9:21`, `21:9` | No | Aspect ratio of the output. |
| `prompt` | string |  | Any text | No | A prompt to guide the reframing generation. |
| `grid_position_x` | integer |  | Pixels | No | The x position of the input in the grid, in pixels. Controls horizontal positioning of the source within the target output dimensions. |
| `grid_position_y` | integer |  | Pixels | No | The y position of the input in the grid, in pixels. Controls vertical positioning of the source within the target output dimensions. |
| `x_start` | integer |  | Pixels | No | The x start of the crop bounds. Defines the left boundary where your source will be placed in the output frame. |
| `x_end` | integer |  | Pixels | No | The x end of the crop bounds. Defines the right boundary where your source will be placed in the output frame. The distance between `x_start` and `x_end` determines the resized width of your content. |
| `y_start` | integer |  | Pixels | No | The y start of the crop bounds. Defines the top boundary where your source will be placed in the output frame. |
| `y_end` | integer |  | Pixels | No | The y end of the crop bounds. Defines the bottom boundary where your source will be placed in the output frame. The distance between `y_start` and `y_end` determines the resized height of your content. |

### Output
`output` is a single URL (string) pointing to the reframed 720p video.

### Status Codes

| Status code | Meaning | What to do |
|-------------|---------|------------|
| 200 OK | GET returned the prediction | Check `status`; keep polling while it is `starting` or `processing`. |
| 201 Created | POST accepted, prediction created | Success. Poll GET `/predictions/{id}` with the returned `id`. |
| 400 Bad Request | Invalid input (for example no video URL, an unreachable video URL or an unsupported `aspect_ratio`) | Fix the request body and send it again. |
| 401 Unauthorized | Missing or invalid API key | Send a valid key in the `x-api-market-key` header. |
| 403 Forbidden | The key is not allowed to use this API | Check your subscription for this API. |
| 404 Not Found | Unknown prediction ID or wrong URL | Check the base URL and the prediction `id`. |
| 429 Too Many Requests | Rate limit exceeded | Wait and retry with backoff. |
| 500 Internal Server Error | Server-side error | Retry; if it keeps happening, contact us. |
| 503 Service Unavailable | Service temporarily unavailable | Retry after a short wait. |

### Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide

### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video";

async function createAndWaitForPrediction(inputData) {
  // Step 1: create the prediction (201 Created on success)
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "7a27619ccb64e4f1942e9a53e503142be08d505587313afa1da037b631a6760e", input: inputData })
  });

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

  const prediction = await response.json();

  // Step 2: poll for the result
  return await pollForResults(prediction.id);
}

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 between checks
  const startTime = Date.now();

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

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

    const prediction = await response.json();

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

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

    await delay(POLL_INTERVAL);
  }

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

createAndWaitForPrediction({
  "video_url": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "aspect_ratio": "9:16"
})
  .then(output => console.log(output))
  .catch(error => console.error(error));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video"

def create_and_wait_for_prediction(input_data):
    # Step 1: create the prediction (201 Created on success)
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers={"Content-Type": "application/json", "x-api-market-key": API_KEY},
        json={"version": "7a27619ccb64e4f1942e9a53e503142be08d505587313afa1da037b631a6760e", "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    # Step 2: poll for the result
    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks
    headers = {"x-api-market-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"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(POLL_INTERVAL)

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

print(create_and_wait_for_prediction({
    "video_url": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
    "aspect_ratio": "9:16"
}))
```

#### cURL
```bash
# Step 1: create a prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7a27619ccb64e4f1942e9a53e503142be08d505587313afa1da037b631a6760e",
    "input": {
      "video_url": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
      "aspect_ratio": "9:16"
    }
  }'

# Step 2: check the prediction (replace PREDICTION_ID with the id from step 1)
# Repeat about once per second until status is succeeded, failed or canceled.
curl -X GET "https://prod.api.market/api/v1/magicapi/change-video-aspect-ratio-luma-reframe-video/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Trim your clip to the part you need before sending it: you pay per second of output video.
- Send the video in `video` rather than the deprecated `video_url`.
- Leave the grid position and crop bound fields out unless you need precise placement.

## FAQ

**How long can the input video be?**
The model's field descriptions give a maximum video duration of 10 seconds.

**What resolution is the output?**
Outputs are 720p.

**How is a request billed?**
Per second of output video at $0.075 per second, rounded up to a whole second. A 5 second clip costs $0.375.

**Should I use `video` or `video_url`?**
Use `video`. `video_url` is marked deprecated in the model schema, although it still works (the example above used it).

## 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@magicapi.com.


Change a video's aspect ratio with Luma Reframe Video. Choose from 1:1, 3:4, 4:3, 9:16, 16:9, 9:21 or 21:9. 720p output, $0.075 per second of video.