---
type: AI Model
id: video-crop-api
title: Video Crop API
provider: Pixazo
description: "Crop a video to an aspect ratio or an exact box. Pass aspect_ratio like \"9:16\" for Reels, Shorts and TikTok and the frame is centre-cropped without distorting the picture — the subject stays the right shape, it is not squeezed. Or give width and height (with optional x and y) for an exact box. Pass a video_url, poll the request, then download the MP4."
resource: https://www.pixazo.ai/models/video-crop-api
docs_url: https://www.pixazo.ai/models/video-crop-api
latest_version: v1
tags:
  - video-cropper
  - pixazo
variants:
  - id: media-crop-v1
    name: Video Crop 1.0
    version: 1.0
    capabilities:
      - Crop
timestamp: 2026-08-25T08:44:38.582Z
---

# Video Crop API

> Provider: **Pixazo**
> Source: https://www.pixazo.ai/models/video-crop-api

Crop a video to an aspect ratio or an exact box. Pass aspect_ratio like "9:16" for Reels, Shorts and TikTok and the frame is centre-cropped without distorting the picture — the subject stays the right shape, it is not squeezed. Or give width and height (with optional x and y) for an exact box. Pass a video_url, poll the request, then download the MP4.

## Video Crop 1.0

### Crop

## Base URL

```
https://gateway.pixazo.ai/media-tools/v1/video-crop
```

## Authentication

All requests require an API key passed via header.

**Pricing:** Billed at **$0.002 per second of input video** — measured on the source you submit, not on the file returned. A 60-second video costs $0.12.

**Rounding:** billing is per second but always rounds **up to a whole second** — a 5.06-second source bills as 6 seconds. The shortest billable job is 1 second.

**Retries:** this is an asynchronous job on shared encoding capacity, so a request can occasionally come back `processing_failed` or take much longer than usual. These are transient and succeed on a retry, and a failed job is **never charged** — the wallet hold is released. If you chain these tools, retry a failed step rather than failing the whole pipeline.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Video Crop generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/media-tools/v1/video-crop
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov",
    "aspect_ratio": "9:16"
}
```

```
import requests

url = "https://gateway.pixazo.ai/media-tools/v1/video-crop"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov",
    "aspect_ratio": "9:16"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = "https://gateway.pixazo.ai/media-tools/v1/video-crop";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov",
    "aspect_ratio": "9:16"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/media-tools/v1/video-crop" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov",
    "aspect_ratio": "9:16"
  }'
```

## Output

```
{
  "request_id": "media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=media-tools&operation=video-crop)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Video Crop generate request

Parameter

Required

Type

Default

Allowed values / range

Description

video\_url

Yes

string

—

HTTP(S) URL; ≤ 500 MB, ≤ 600 s

Publicly reachable HTTP(S) URL of the source video.

aspect\_ratio

Conditional

string

—

`W:H` — e.g. `9:16`, `1:1`, `16:9`, `4:5`, `1.85:1`

Centre-crops the largest area of exactly this ratio, so the subject keeps its shape — the picture is never squeezed. Give this **or** `width` + `height`; if both are sent, `width` + `height` wins. `9:16` is the Reels / Shorts / TikTok crop. Decimal ratios such as `1.85:1` are accepted, and `x` or `/` also work as separators (`9x16`). A ratio the source is too small to fit is rejected with 400.

width

Conditional

integer

—

positive integer, pixels; the box must fit inside the source frame

Exact crop width. Must be sent together with `height` — one without the other is ignored and the request falls back to `aspect_ratio`. Send a JSON number, not a quoted string. Takes precedence over `aspect_ratio`.

height

Conditional

integer

—

positive integer, pixels; the box must fit inside the source frame

Exact crop height. Use together with `width`. Send a JSON number, not a quoted string.

x

No

integer

centred

integer, pixels from the left edge

Left edge of the crop box. Only used with `width` + `height`; ignored when you crop by `aspect_ratio`, which is always centred. Omit for a centred box.

y

No

integer

centred

integer, pixels from the top edge

Top edge of the crop box. Only used with `width` + `height`; ignored when you crop by `aspect_ratio`. Omit for a centred box.

## Example Request

```
{
  "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov",
    "aspect_ratio": "9:16"
}
```

## Response

```
{
  "request_id": "media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'media-crop' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "media-crop",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "media-crop_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "media-crop",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/media-crop_019dxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.