> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Video enhancement

> Enhance existing videos with BytePlus AI MediaKit through a dedicated asynchronous GENGEN endpoint.

BytePlus Video Enhancement improves clarity, reduces noise and compression artifacts, upscales resolution, and optionally interpolates frames. Use the public model ID `byteplus-video-enhancement`.

## Workflow

1. Submit a public source URL to `POST /api/gengen/v1/video/enhancements` with your GENGEN API key.
2. Save the returned `id`. Query `GET /api/gengen/v1/video/enhancements/{id}` with the same API key until the status is `succeeded` or `failed`. Use a polling interval of at least 10 seconds.
3. Read the video URL from `outputs.videos[0]` and download it before `outputs.expiresAt`.

GENGEN receives BytePlus completion notifications and also reconciles tasks in the background. Closing your client does not cancel processing. This release does not provide customer webhook subscriptions, task cancellation, or a dedicated list endpoint. Submit each job once; a new POST creates a new billable job.

<Warning>
  Result URLs normally expire after 24 hours. The returned `outputs.expiresAt` is the applicable deadline. GENGEN does not archive or transfer these results to permanent storage. After that deadline, retrieval returns the task record with an empty `outputs.videos` array; it does not regenerate or extend the result.
</Warning>

## Source requirements

* A public HTTP or HTTPS URL reachable without headers or cookies. Signed URLs are accepted; keep the URL valid while the job waits and processes.
* BytePlus supports source video up to **2K** and recommends files no larger than **10 GB**. Media compatibility is checked by BytePlus during processing.
* Supply `assets.sourceVideo`; direct file uploads and `asset://` identifiers are not accepted here.

GENGEN validates request fields and URL syntax, then reserves a fixed balance amount. It does not download or probe the video before submission. Source download or format errors may therefore appear as an asynchronous task failure.

## Options

| Field | Values | Default |
| - | - | - |
| `model` | `byteplus-video-enhancement` | Required |
| `mode` | `video_enhancement` | `video_enhancement` |
| `controls.resolution` | `1080p`, `2k`, `4k` | `1080p` |
| `controls.fps` | `30`, `60`; omit to preserve the source frame rate | Source frame rate |
| `providerOptions.byteplus.toolVersion` | `standard`, `professional` | `standard` |
| `providerOptions.byteplus.enhanceStyle` | `natural`, `hd` | `natural` |
| `providerOptions.byteplus.scene` | `common`, `ugc`, `short_series`, `aigc`, `old_film` | `aigc` (Standard only) |

Omit `scene` for Professional. `natural` favors a natural appearance; `hd` favors stronger sharpness. Output uses the upstream default MP4 format. Prompt text, custom codecs, bit depth, and arbitrary provider parameters are not supported.

## Example

```bash theme={"dark"}
curl --request POST 'https://gengen.farm/api/gengen/v1/video/enhancements' \
  --header "Authorization: Bearer $GENGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "byteplus-video-enhancement",
    "mode": "video_enhancement",
    "assets": { "sourceVideo": "https://example.com/source.mp4" },
    "controls": { "resolution": "1080p", "fps": 30 },
    "providerOptions": {
      "byteplus": { "toolVersion": "standard", "enhanceStyle": "natural", "scene": "aigc" }
    }
  }'
```

```json theme={"dark"}
{
  "id": "byteplus-enhance:12345678-1234-4234-8234-123456789abc",
  "model": "byteplus-video-enhancement",
  "status": "pending",
  "outputs": { "videos": [], "images": [] }
}
```

```bash theme={"dark"}
curl 'https://gengen.farm/api/gengen/v1/video/enhancements/byteplus-enhance:12345678-1234-4234-8234-123456789abc' \
  --header "Authorization: Bearer $GENGEN_API_KEY"
```

```json theme={"dark"}
{
  "id": "byteplus-enhance:12345678-1234-4234-8234-123456789abc",
  "model": "byteplus-video-enhancement",
  "status": "succeeded",
  "outputs": {
    "videos": ["https://example.com/enhanced.mp4"],
    "images": [],
    "expiresAt": "2026-10-08T12:00:00.000Z"
  },
  "createdAt": "2026-10-07T11:58:00.000Z",
  "updatedAt": "2026-10-07T12:00:00.000Z"
}
```

## Billing and failures

A fixed amount is reserved before processing; it is not a quote or a maximum charge. Successful jobs are charged by actual output duration, enhancement version, resolution, and frame-rate tier. Any unused reservation is released. Costs above the reservation use additional available balance. If the final balance is insufficient, retrieval returns HTTP 402; top up and retry retrieval of the same task. Output expiration still applies. Repeated retrieval and duplicate completion notifications do not charge again. Failed jobs release their reserved balance. Check [live customer pricing](/pricing) before use.

Statuses are `pending`, `running`, `succeeded`, and `failed`. A failed result includes `failureReason`. Invalid requests return HTTP 400, invalid API keys return 401, insufficient balance returns 402, and tasks unavailable to the requesting key return 404. If submission acceptance is uncertain, the task can remain in progress while GENGEN reconciles it; avoid submitting a replacement job automatically.

See [Create task](/api-reference/byteplus/video-enhancement/create-task) and [Retrieve task](/api-reference/byteplus/video-enhancement/retrieve-task) for the endpoint schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.