Name: 720p Video Generation API (Luma Ray 2)
Brand: magicapi
SKU: api-magicapi-generate-hd-videos-luma-ray-2-720p
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 720p Video Generation API (Luma Ray 2)

## Overview
Ray 2 (720p) is a video generation model from Luma AI. It generates 720p videos of 5 or 9 seconds from a text `prompt`. You can also give it an image to use as the first frame (`start_image`), the last frame (`end_image`), or both, make the video loop, and add camera concepts such as `orbit_left` or `aerial_drone`.

Only `prompt` is required. Each request returns the URL of one video.

## Features
- **Text to video:** describe the scene in `prompt`.
- **First and last frames:** pass `start_image`, `end_image` or both to control how the video starts and ends.
- **Duration:** `5` (default) or `9` seconds.
- **Aspect ratios:** `1:1`, `3:4`, `4:3`, `9:16`, `16:9` (default), `9:21`, `21:9`.
- **Looping:** set `loop` to `true` so the last frame matches the first for continuous playback.
- **Camera concepts:** pass a list of camera concepts in `concepts`, for example `["orbit_left"]` or `["aerial_drone", "push_in"]`. The available concepts are: truck_left, pan_right, pedestal_down, low_angle, pedestal_up, selfie, pan_left, roll_right, zoom_in, over_the_shoulder, orbit_right, orbit_left, static, tiny_planet, high_angle, bolt_cam, dolly_zoom, overhead, zoom_out, handheld, roll_left, pov, aerial_drone, push_in, crane_down, truck_right, tilt_down, elevator_doors, tilt_up, ground_level, pull_out, aerial, crane_up, eye_level.
- `start_image_url` and `end_image_url` are deprecated; use `start_image` and `end_image` instead.

## Use Cases
1. **Short social and marketing clips:** 5 or 9 second videos in vertical (`9:16`), square (`1:1`) or widescreen (`16:9`) formats.
2. **Animating a still image:** use a photo or illustration as `start_image` and describe the motion in the prompt.
3. **Transitions between two images:** set both `start_image` and `end_image` to generate the movement from one to the other.
4. **Looping backgrounds:** set `loop` to `true` for clips that repeat without a visible cut.

## Visual Examples
This is a real request sent through api.market and the file it returned.

Prompt: "A barista slides a latte across a wooden counter, cinematic close-up"

Duration: 5 seconds. All other fields were left at their defaults (`16:9`, no loop, no images, no camera concepts).

**Output video:** [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/ray-2-720p-output-api-market.mp4)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.225 per API unit.
- **1 API unit** = 1 second of output video, rounded up to the next whole second. There are no variants or tiers: every second costs the same, and the number of seconds follows the `duration` you request:
  - `duration` 5 (default): 5 units, 5 x $0.225 = **$1.125** per video
  - `duration` 9: 9 units, 9 x $0.225 = **$2.025** per video
- **Worked example:** the example above asked for a 5 second video and was billed 5 units = $1.125.
- **Failed or cancelled predictions** are not billed.
- **GET requests** to check prediction status (GET /api/v1/magicapi/generate-hd-videos-luma-ray-2-720p/predictions/{id}) 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/generate-hd-videos-luma-ray-2-720p`

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

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.
1. POST `/predictions` with the model `version` and your `input`.
2. The API returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the request was accepted; it is not an error.
3. Poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
4. When `status` is `succeeded`, `output` holds the URL of the generated video.
5. When `status` is `failed`, the `error` field explains why.

The example request above took about 1.5 minutes to finish, so allow a generous timeout when polling.

### Endpoints

#### Create a Prediction
`POST /predictions`

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "3ca2bc3597e124149bcae1f9c239790a58ba0f1aa72e1c8747192d2b44284dc4",
    "input": {
      "prompt": "A barista slides a latte across a wooden counter, cinematic close-up",
      "duration": 5
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "3ca2bc3597e124149bcae1f9c239790a58ba0f1aa72e1c8747192d2b44284dc4",
  "status": "starting",
  "created_at": "2026-10-13T11:13:19.540Z"
}
```

#### Check Prediction Status
`GET /predictions/{id}`

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response (200 OK) once the prediction has finished:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "input": {
    "prompt": "A barista slides a latte across a wooden counter, cinematic close-up",
    "duration": 5
  },
  "output": "https://blog.api.market/wp-content/uploads/2026/10/ray-2-720p-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-13T11:13:19.540Z",
  "started_at": "2026-10-13T11:13:20.540Z",
  "completed_at": "2026-10-13T11:14:49.390Z"
}
```

### Input Parameters
| Parameter | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `prompt` | string | Yes | none |  | Text prompt for video generation |
| `duration` | integer | No | `5` | `5`, `9` | Duration of the video in seconds |
| `aspect_ratio` | string | No | `16:9` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `9:21`, `21:9` | Aspect ratio of the generated video |
| `concepts` | array of strings | No | none | See the list in Features | List of camera concepts to apply to the video generation |
| `end_image` | string (URL) | No | none |  | An optional last frame of the video to use as the ending frame. |
| `end_image_url` | string | No | none |  | Deprecated: Use end_image instead |
| `loop` | boolean | No | `false` |  | Whether the video should loop, with the last frame matching the first frame for smooth, continuous playback. |
| `start_image` | string (URL) | No | none |  | An optional first frame of the video to use as the starting frame. |
| `start_image_url` | string | No | none |  | Deprecated: Use start_image instead |

### Output
`output` is a single URL (string) pointing to the generated MP4 video.

## Status Codes
- **200 OK:** prediction status returned.
- **201 Created:** prediction accepted. Poll GET `/predictions/{id}` for the result.
- **400 Bad Request:** invalid or missing input fields.
- **401 Unauthorized:** missing or invalid API key.
- **404 Not Found:** unknown prediction 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.

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

## Error Handling
- **Request errors (4xx):** check the response body, fix the input fields and send the request again.
- **Failed predictions:** when GET returns `status: "failed"`, read the `error` field. Failed predictions are not billed.
- **Rate limits (429) and server errors (5xx):** retry with exponential backoff.

## Implementation Guide

### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p";

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

async function waitForPrediction(id, timeoutMs = 1200000, intervalMs = 5000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const response = await fetch(`${baseUrl}/predictions/${id}`, {
      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 new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  throw new Error("Timed out waiting for the prediction");
}

const prediction = await createPrediction({
  "prompt": "A barista slides a latte across a wooden counter, cinematic close-up",
  "duration": 5
});
const output = await waitForPrediction(prediction.id);
console.log(output);
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p"

def create_prediction(input_data):
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers={"Content-Type": "application/json", "x-api-market-key": API_KEY},
        json={"version": "3ca2bc3597e124149bcae1f9c239790a58ba0f1aa72e1c8747192d2b44284dc4", "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    return response.json()

def wait_for_prediction(prediction_id, timeout=1200, interval=5):
    start = time.time()
    while time.time() - start < timeout:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-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"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'unknown error'}")
        time.sleep(interval)
    raise Exception("Timed out waiting for the prediction")

prediction = create_prediction({
  "prompt": "A barista slides a latte across a wooden counter, cinematic close-up",
  "duration": 5
})
print(wait_for_prediction(prediction["id"]))
```

### cURL
```bash
# Step 1: create the prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "3ca2bc3597e124149bcae1f9c239790a58ba0f1aa72e1c8747192d2b44284dc4",
    "input": {
      "prompt": "A barista slides a latte across a wooden counter, cinematic close-up",
      "duration": 5
    }
  }'

# Step 2: poll with the returned id until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/generate-hd-videos-luma-ray-2-720p/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## FAQ
**Q: Can I start from an image?**  
A: Yes. Pass an image URL as `start_image` to use it as the first frame, `end_image` to use it as the last frame, or both.

**Q: Which durations are available?**  
A: 5 or 9 seconds. You are billed per second of video, so 5 seconds costs $1.125 and 9 seconds costs $2.025.

**Q: How do I add camera motion?**  
A: Pass one or more concept names in `concepts`, for example `["orbit_left"]`. The full list is in the Features section.

**Q: What if my prediction fails?**  
A: Failed predictions are not billed. Read the `error` field, adjust the input and try again.

**Q: Is POST returning 201 an error?**  
A: No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## 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 Ray 2 API: generate 5 or 9 second 720p videos from text, with optional start and end images, looping and camera concepts. $0.225 per second.