> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ltx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ltx.io/_mcp/server.

# Extract a mask from a video

POST https://api.ltx.io/v2/video-alpha-gen
Content-Type: application/json

Separate the foreground of a video from its background. On completion, the result contains two files:

* `matte_video_url`: a grayscale mask (alpha matte) MP4. White is foreground, black is transparent, and shades of gray are partly transparent.
* `cutout_video_url`: the input video with the mask as its alpha channel, as a ProRes 4444 `.mov` with straight (not premultiplied) alpha, ready to composite. ProRes files are large: roughly 42 MB per second of video at 1080p and 172 MB per second at 4K.

Both files have the same frames as the input, one for one. They have the input's resolution (an odd width or height is rounded down to an even number) and the input's frame rate, rounded to a whole number. They have no audio.

Responds immediately with the job `id` and `created_at` timestamp. Poll `GET /v2/video-alpha-gen/{id}` until the status is `completed`.

Requests that violate the content policy fail the job with `content_filtered_error`. An account without enough credit fails the same way, with `insufficient_funds_error`.

Billed per second of input video. See [Pricing](/pricing).

Reference: https://docs.ltx.io/api-documentation/api-reference/async-video-generation/submit-video-alpha-gen

## Authentication

- `Authorization` header (bearer token, required) — API key authentication

## Request

### Body (application/json)

This endpoint expects a VideoAlphaGenRequest.

- `video_uri` (string, required) — Input video in HTTPS URL or base64 data URI format. See [Input Formats](/input-formats#videos) for supported formats and codecs. Max 3,072 frames (e.g. about 2 minutes at 24fps, or about 1 minute 42 seconds at 30fps) and 200 MB ([data URIs](/input-formats#data-uri-base64) have a lower limit). The long side can be up to 3840 pixels and the short side up to 2160 pixels, so 4K video is accepted in landscape (3840×2160) or portrait (2160×3840). The long side can be at most 32:9 times the short side (e.g. 3840×1080). The frame rate must be at least 1 fps.

## Response

### 202

Job submitted successfully

- `id` (string, required) — Unique job identifier. Use this to poll for status.
- `created_at` (datetime, required) — ISO 8601 timestamp of when the job was created.

## Errors

### 400 Bad Request Error

The request is invalid or malformed

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

### 401 Unauthorized Error

Authentication failed

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

### 413 Content Too Large Error

The request body exceeds 32 MB

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

### 429 Too Many Requests Error

Queue limit exceeded

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

### 500 Internal Server Error

An unexpected error occurred

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

### 503 Service Unavailable Error

Service temporarily unavailable

- `type` (enum, required) — Response type indicator
  - Allowed values: `error`
- `error` (ErrorError, required)

## Types

### ErrorError

- `type` (string, required) — Error type for programmatic handling
- `message` (string, required) — Human-readable error description

## Examples

**Request**

```json
{
  "video_uri": "YOUR_VIDEO_URI"
}
```

**Response**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-01-15T10:00:00.000Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.ltx.io/v2/video-alpha-gen"

payload = { "video_uri": "YOUR_VIDEO_URI" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ltx.io/v2/video-alpha-gen"

	payload := strings.NewReader("{\n  \"video_uri\": \"YOUR_VIDEO_URI\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.ltx.io/v2/video-alpha-gen")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"video_uri\": \"YOUR_VIDEO_URI\"\n}")
  .asString();
```