Name: AI Image Aspect Ratio Changer API (Luma Reframe Image)
Brand: magicapi
SKU: api-magicapi-ai-image-aspect-ratio-adjuster-luma-reframe-image
Availability: InStock
Author: API Market

Shashank Agarwal

# 📐 AI Image Aspect Ratio Changer API (Luma Reframe Image)

## Overview
The **AI Image Aspect Ratio Changer API (Luma Reframe Image)** changes the aspect ratio of a photo without cropping it. You send an image and a target aspect ratio, and Luma's model fills the new frame around your picture instead of cutting parts away. You can guide the result with a `prompt`, choose between the `photon-flash-1` (default) and `photon-1` models, and control in pixels where the source sits inside the output frame. Each request returns a URL to one image.

## Features
- **Reframe without cropping:** turn a landscape photo into a portrait, square or ultra-wide image.
- **Aspect ratios:** `1:1`, `3:4`, `4:3`, `9:16`, `16:9` (default), `9:21` or `21:9`.
- **Two models:** `photon-flash-1` (default) or `photon-1`, which is billed at 3 units per image.
- **Optional prompt:** describe what the generated surroundings should contain.
- **Placement controls:** `grid_position_x` and `grid_position_y` position the source inside the output; `x_start`, `x_end`, `y_start` and `y_end` set the pixel bounds where the source is placed, which also sets its resized width and height.

## Use Cases
### Social Media Formats
Turn one wide photo into a `9:16` story, a `1:1` post and a `16:9` banner without losing the subject.

### Ads and Banners
Fit existing campaign photos into the aspect ratios different ad placements require.

### Product and Catalog Images
Give product photos the same frame shape across a store, adding background instead of cropping the product.

### Print and Thumbnails
Prepare an image for a different print or thumbnail shape while keeping the full original picture.

## Visual Examples
This is the real request we sent through api.market and the image it produced. The input photo was passed in `image_url` and reframed to `9:16`; all other fields were left at their defaults (model `photon-flash-1`, no prompt).

**Input image:** [View the input image](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp)

**Output (9:16):**

![The input photo of a woman in a yellow raincoat on a rainy city street at night, reframed to a tall 9:16 portrait with an api.market neon sign above her](https://blog.api.market/wp-content/uploads/2026/10/reframe-image-output-api-market.jpg)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.013 per API unit.
- **Billing unit:** each request returns one image. The number of units depends on the `model` you choose:
  - **`photon-flash-1`** (the default): 1 unit per image = **$0.013 per image**
  - **`photon-1`**: 3 units per image = **$0.039 per image**
- The example on this page used the default `photon-flash-1`, so it cost $0.013.
- Aspect ratio, prompt and placement settings do not change the price.
- **Failed or cancelled predictions** are not billed.
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation
### Base URL
```
https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image
```

### 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
**IMPORTANT:** This API is asynchronous.
1. Send `POST /predictions` with the model `version` and your `input`. A successful call 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}` every second or two.
3. Stop when `status` is `succeeded` (the `output` field holds the image URL), `failed` (see the `error` field) or `canceled`.

### Endpoints

#### POST /predictions
Create a prediction. This is the request used for the example on this page:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7adc71e1414f484b23b60f10889e75cf5f2093b3d7a50bf36d0d818543209720",
    "input": {
      "image_url": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
      "aspect_ratio": "9:16"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "7adc71e1414f484b23b60f10889e75cf5f2093b3d7a50bf36d0d818543209720",
  "status": "starting",
  "created_at": "2026-10-12T10:43:32.271Z"
}
```

#### GET /predictions/{id}
Check the status of a prediction.
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/reframe-image-output-api-market.jpg",
  "error": null,
  "created_at": "2026-10-12T10:43:32.271Z",
  "started_at": "2026-10-12T10:43:32.312Z",
  "completed_at": "2026-10-12T10:43:41.271Z"
}
```

`output` is a single URL to the generated image.

### Input Parameters
| Parameter | Type | Default | Allowed values | Required | Description |
|---|---|---|---|---|---|
| `image` | string (URI) | none | Image URL | No | The image to reframe. This is the current field for the input photo. |
| `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 | none | Any text | No | A prompt to guide the reframing generation. |
| `model` | string | `photon-flash-1` | `photon-flash-1`, `photon-1` | No | The model to use for the reframe generation. `photon-1` costs 3 units per image. |
| `grid_position_x` | integer | none | Pixels | No | The x position of the input in the grid. Controls horizontal positioning of the source within the target output dimensions. |
| `grid_position_y` | integer | none | Pixels | No | The y position of the input in the grid. Controls vertical positioning of the source within the target output dimensions. |
| `x_start` | integer | none | Pixels | No | Left boundary where the source is placed in the output frame. The distance between `x_start` and `x_end` sets the resized width of your content. |
| `x_end` | integer | none | Pixels | No | Right boundary where the source is placed in the output frame. |
| `y_start` | integer | none | Pixels | No | Top boundary where the source is placed in the output frame. The distance between `y_start` and `y_end` sets the resized height of your content. |
| `y_end` | integer | none | Pixels | No | Bottom boundary where the source is placed in the output frame. |
| `image_url` | string | none | Image URL | No | URL of the image to reframe. Deprecated: it still works (the example on this page uses it), but prefer `image` in new code. |

The schema marks no field as required, but every request needs an input photo in `image` or `image_url`.

### Status Codes
- **201 Created:** Prediction created (POST). This is the normal success response.
- **200 OK:** Prediction details returned (GET).
- **400 Bad Request:** Invalid input, for example an unreachable image URL or an unsupported `aspect_ratio` or `model`.
- **401 Unauthorized:** Missing or invalid API key.
- **404 Not Found:** No prediction with that ID.
- **429 Too Many Requests:** Too many requests in a short time. Wait and retry.
- **500 Internal Server Error:** Server-side error. Retry after a short wait.

### Error Handling
- A 201 response only means the prediction was accepted. Always poll until `status` is `succeeded`, `failed` or `canceled`.
- When `status` is `failed`, read the `error` field, fix the input and send a new request. Failed predictions are not billed.
- For 429 and 5xx responses, retry with exponential backoff.

## 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
### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image";
const version = "7adc71e1414f484b23b60f10889e75cf5f2093b3d7a50bf36d0d818543209720";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function reframeImage(input) {
  const createResponse = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version, input })
  });
  if (createResponse.status !== 201 && createResponse.status !== 200) {
    throw new Error(`API error: ${createResponse.status} ${await createResponse.text()}`);
  }
  const { id } = await createResponse.json();

  const deadline = Date.now() + 10 * 60 * 1000;
  while (Date.now() < deadline) {
    const pollResponse = await fetch(`${baseUrl}/predictions/${id}`, {
      headers: { "x-api-market-key": apiKey }
    });
    if (!pollResponse.ok) {
      throw new Error(`API error: ${pollResponse.status} ${await pollResponse.text()}`);
    }
    const prediction = await pollResponse.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(1000);
  }
  throw new Error("Prediction timed out after 10 minutes");
}

reframeImage({
  "image_url": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
  "aspect_ratio": "9:16"
}).then((url) => console.log("Image:", url));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image"
VERSION = "7adc71e1414f484b23b60f10889e75cf5f2093b3d7a50bf36d0d818543209720"

def reframe_image(input_data, timeout_seconds=600):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": VERSION, "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    prediction_id = response.json()["id"]

    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        poll = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-key": API_KEY},
        )
        poll.raise_for_status()
        prediction = poll.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error')}")
        time.sleep(1)
    raise TimeoutError("Prediction timed out")

url = reframe_image({
  "image_url": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
  "aspect_ratio": "9:16"
})
print("Image:", url)
```

### cURL
```bash
# Step 1: create the prediction (returns 201 with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7adc71e1414f484b23b60f10889e75cf5f2093b3d7a50bf36d0d818543209720",
    "input": {
      "image_url": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
      "aspect_ratio": "9:16"
    }
  }'

# Step 2: poll with the id from step 1 until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-aspect-ratio-adjuster-luma-reframe-image/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Tips
- Use `image` for new integrations; `image_url` is deprecated.
- Add a short `prompt` describing the surroundings (for example "a wide sandy beach") when the default fill does not match what you want.
- Try `photon-flash-1` first; switch to `photon-1` for a final version if you want the other model's result, at 3 times the price.

## FAQ
### Does this crop my image?
No. The model fills the new frame around your photo instead of cutting parts of it away.

### Which input field should I use, `image` or `image_url`?
`image` is the current field. `image_url` is deprecated but still accepted, and it is what the example on this page used.

### What does each model cost?
`photon-flash-1` (the default) is 1 unit ($0.013) per image and `photon-1` is 3 units ($0.039) per image.

### What happens if a prediction fails?
It is not billed. Read the `error` field, fix the input and try again.

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


Luma Reframe Image API: change a photo to 1:1, 3:4, 4:3, 9:16, 16:9, 9:21 or 21:9 without cropping. $0.013 per image with photon-flash-1, $0.039 with photon-1.