Name: Luma Ray 3.2 Text and Image to Video API
Brand: magicapi
SKU: api-magicapi-cinematic-video-generator-luma-ray-3-2
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Text and Image to Video API with HDR (Luma Ray 3.2)

## Overview
Ray 3.2 is a video model from Luma. Its developer describes it as a reasoning video model that generates cinematic 5 or 10 second videos from text or images, with native HDR and EXR export for professional production pipelines.

Send a text `prompt` to generate a video. Add an optional `start_image` and `end_image` to fix the first and last frames. Choose 540p, 720p or 1080p, a 5 or 10 second length, HDR output, EXR export and seamless looping. Each request returns the URL of one MP4 video.

## Features
- **Text-to-video**: describe subject, motion, camera movement, lighting and pacing in `prompt`.
- **Image-to-video**: `start_image` sets the first frame and `end_image` sets the last frame (5 second videos only).
- **Resolutions**: `540p`, `720p` (default) or `1080p`.
- **Durations**: `5` (default) or `10` seconds. 10 seconds is not supported with `hdr`, `start_image`, `end_image` or `loop`.
- **HDR**: set `hdr` to `true` for an HDR-encoded MP4. Requires 720p or 1080p, a 5 second duration and no loop.
- **EXR export**: set `exr_export` to `true` to export an EXR file alongside the MP4 for colour-grading workflows. Requires `hdr` set to `true`.
- **Looping**: set `loop` to `true` for a seamlessly looping video. Not supported with 10 second duration, `hdr` or `end_image`.
- **Aspect ratios**: `9:16`, `3:4`, `1:1`, `4:3`, `16:9` (default), `21:9`. Ignored when `start_image` or `end_image` is set; the ratio then follows the image.

## Use Cases
1. **Short cinematic shots**: product close-ups, food scenes and establishing shots from a written description.
2. **Animating a still**: bring a photo or illustration to life by passing it as `start_image`.
3. **Controlled transitions**: set both `start_image` and `end_image` to move between two frames.
4. **Post-production pipelines**: HDR output and EXR export for footage that will be colour graded.
5. **Background loops**: seamless loops for websites and displays.

## Visual Examples
### Example Input
Prompt: "A barista pours steamed milk into a latte, forming a leaf pattern, slow push-in close-up with soft morning window light."

`resolution`: `540p`, `duration`: `5`. All other fields were left at their defaults (`aspect_ratio` `16:9`, no HDR, no EXR export, no loop, no start or end image).

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/ray-3-2-output-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | Text prompt describing the video. Be specific about subject, motion, camera movement, lighting, and pacing. |
| `aspect_ratio` | string | No | `16:9` | `9:16`, `3:4`, `1:1`, `4:3`, `16:9`, `21:9` | Aspect ratio of the generated video. Ignored when start_image or end_image is set; the model derives the ratio from the anchor frame(s). |
| `resolution` | string | No | `720p` | `540p`, `720p`, `1080p` | Output resolution. 540p is not available when hdr is true. |
| `duration` | integer | No | `5` | `5`, `10` | Video duration in seconds. 10s is not supported with hdr, start_image, end_image, or loop. |
| `hdr` | boolean | No | `false` |  | Generate HDR-encoded MP4. Requires 720p or 1080p, 5s duration, and no loop. |
| `exr_export` | boolean | No | `false` |  | Export an EXR file alongside the MP4 for professional colour-grading workflows. Requires hdr=true. |
| `loop` | boolean | No | `false` |  | Generate a seamlessly looping video. Not supported with 10s duration, hdr, or end_image. |
| `start_image` | string (URL) | No | none |  | Optional first frame of the video. Only valid with 5s duration. |
| `end_image` | string (URL) | No | none |  | Optional last frame of the video. Only valid with 5s duration; not supported with loop. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.1875 per API unit.
- **Billing base: 1 video** (one successful request). The number of API units per video depends on `resolution`, `duration`, `hdr` and `exr_export`; when several rows match a request, the highest one applies:

| Settings | API units | Price per video |
| --- | --- | --- |
| 540p, 5 s | 1 | $0.1875 |
| 720p, 5 s (default) | 2 | $0.375 |
| 540p, 10 s | 3 | $0.5625 |
| 720p, 10 s | 6 | $1.125 |
| 1080p, 5 s | 8 | $1.50 |
| 1080p, 10 s | 24 | $4.50 |
| `hdr` on, 720p (5 s) | 4 | $0.75 |
| `hdr` on, 1080p (5 s) | 16 | $3.00 |
| `exr_export` on (with `hdr`), 720p (5 s) | 6 | $1.125 |
| `exr_export` on (with `hdr`), 1080p (5 s) | 24 | $4.50 |

- **When fields are omitted** the defaults apply: `resolution` `720p`, `duration` `5`, `hdr` `false`, `exr_export` `false`, which is 2 units = $0.375 per video.
- **The example above** (540p, 5 seconds) used 1 unit and cost $0.1875.
- Aspect ratio, looping and start or end images 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
All API requests go to: `https://prod.api.market/api/v1/magicapi/cinematic-video-generator-luma-ray-3-2`

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

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 2 seconds and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/cinematic-video-generator-luma-ray-3-2/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6e0a55010a0a28e18fca6fca8774b6791dde643648f6ac3e98209f5a96ca3c6c",
    "input": {
      "prompt": "A barista pours steamed milk into a latte, forming a leaf pattern, slow push-in close-up with soft morning window light.",
      "resolution": "540p",
      "duration": 5
    }
  }'
```

Response (201 Created):
```json
{
  "id": "m7sydtyg0srmw0d17gebetb8q0",
  "version": "6e0a55010a0a28e18fca6fca8774b6791dde643648f6ac3e98209f5a96ca3c6c",
  "status": "starting",
  "created_at": "2026-10-14T20:31:23.779Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/cinematic-video-generator-luma-ray-3-2/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "m7sydtyg0srmw0d17gebetb8q0",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/ray-3-2-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-14T20:31:23.779Z",
  "started_at": "2026-10-14T20:31:24.779Z",
  "completed_at": "2026-10-14T20:33:23.779Z"
}
```

`output` is a single URL string pointing to the generated MP4 video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt` or a `duration` other than 5 or 10.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## 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
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why, for example when a combination is not supported (10 seconds with `hdr`, `loop` or a start or end image, `hdr` at 540p, or `exr_export` without `hdr`). Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400 or a failed prediction.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/cinematic-video-generator-luma-ray-3-2";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "6e0a55010a0a28e18fca6fca8774b6791dde643648f6ac3e98209f5a96ca3c6c", input })
  });

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

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

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

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 2000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    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(pollInterval);
  }

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

createAndWaitForPrediction({
  "prompt": "A barista pours steamed milk into a latte, forming a leaf pattern, slow push-in close-up with soft morning window light.",
  "resolution": "540p",
  "duration": 5
}).then((output) => console.log(output));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/cinematic-video-generator-luma-ray-3-2"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "6e0a55010a0a28e18fca6fca8774b6791dde643648f6ac3e98209f5a96ca3c6c", "input": input_data},
    )

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

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 2
    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({
    "prompt": "A barista pours steamed milk into a latte, forming a leaf pattern, slow push-in close-up with soft morning window light.",
    "resolution": "540p",
    "duration": 5
}))
```

## FAQ
- **Which settings change the price?**
  - Only `resolution`, `duration`, `hdr` and `exr_export`. The cheapest video is 540p at 5 seconds ($0.1875); the most expensive are 1080p at 10 seconds and 1080p with EXR export ($4.50 each). See the table in Pricing.
- **Can I start from my own image?**
  - Yes. Pass it as `start_image`, and optionally a last frame as `end_image`. Both work only with 5 second videos, and `end_image` cannot be combined with `loop`. When either image is set, `aspect_ratio` is ignored.
- **Which options work with 10 second videos?**
  - 10 second videos work with text prompts at 540p, 720p or 1080p. They do not support `hdr`, `exr_export` (which needs `hdr`), `loop`, `start_image` or `end_image`.
- **What do I need for HDR?**
  - Set `hdr` to `true` with `resolution` `720p` or `1080p`, `duration` `5` and `loop` off. Add `exr_export` for an EXR file alongside the MP4.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, check that the combination of options is supported, 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.


Generate 5 or 10 second videos from text or images with Luma Ray 3.2, at 540p, 720p or 1080p with optional HDR and EXR export. From $0.1875 per video.