From 692317605735b0a6cc6d3dffd79e5684a54b4ba4 Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Sat, 13 Jun 2026 08:59:12 +0300
Subject: [PATCH] docs: document ffmpeg compute param and GPU acceleration

---
 guides/ffmpeg.mdx    | 36 ++++++++++++++++++++++++++++++++++++
 job-types/ffmpeg.mdx | 10 ++++++++++
 2 files changed, 46 insertions(+)

diff --git a/guides/ffmpeg.mdx b/guides/ffmpeg.mdx
index c22c43e..a6fe13a 100644
--- a/guides/ffmpeg.mdx
+++ b/guides/ffmpeg.mdx
@@ -123,6 +123,7 @@ This burns a subtitle track that lives only in the request, with no file to host
 | `params.command` | string | yes | - | Real FFmpeg command starting with `ffmpeg`. Input URLs go in `-i` positions |
 | `params.outputFormat` | string | no | inferred | Override container format. Inferred from trailing filename if omitted |
 | `params.timeout` | int | no | `120` | Server-side max execution in seconds. Range 1–900 |
+| `params.compute` | string | no | `auto` | Machine class: `auto`, `cpu`, or `gpu`. See [GPU acceleration](#gpu-acceleration) |
 
 ## Validate without executing
 
@@ -158,6 +159,41 @@ Returns `{ data: { valid: true, args: [...], inferredOutputFormat: "mp4" } }` or
 
 Unrecognised flags are rejected before dispatch with `VALIDATION_ERROR`.
 
+## GPU acceleration
+
+Your jobs run on CPU-powered or GPU-powered machines. `compute` defaults to `auto`, so a command that uses an NVENC encoder routes to a GPU on its own. You don't send anything.
+
+Switch one flag to move an encode to the hardware encoder. The GPU path runs `h264_nvenc`, `hevc_nvenc`, and `av1_nvenc` on NVIDIA L4 GPUs, several times faster than software `libx264` at the same resolution.
+
+<CodeGroup>
+
+```bash CPU (libx264)
+ffmpeg -i input.mp4 -c:v libx264 -preset medium -crf 23 output.mp4
+```
+
+```bash GPU (h264_nvenc)
+ffmpeg -i input.mp4 -c:v h264_nvenc -preset p5 -cq 23 output.mp4
+```
+
+</CodeGroup>
+
+Set `compute` only to force a choice. `gpu` pins the job to a GPU; `cpu` pins it to CPU and rejects an NVENC command with `VALIDATION_ERROR`.
+
+```json
+{
+  "type": "ffmpeg",
+  "inputs": {},
+  "params": {
+    "command": "ffmpeg -i https://example.com/video.mp4 -c:v h264_nvenc -preset p5 -cq 23 output.mp4",
+    "compute": "gpu"
+  }
+}
+```
+
+<Info>
+GPU jobs require the Pro plan and bill per second at GPU rates. A GPU job on the Free plan returns `403 PLAN_LIMIT`. CPU jobs run on every plan.
+</Info>
+
 ## Security model
 
 Every command is validated before it runs, then executed in an isolated, network-restricted sandbox.
diff --git a/job-types/ffmpeg.mdx b/job-types/ffmpeg.mdx
index 334f877..8f0c522 100644
--- a/job-types/ffmpeg.mdx
+++ b/job-types/ffmpeg.mdx
@@ -123,6 +123,16 @@ res = requests.post(
   Max execution time in seconds. Range 1–900. Plan caps apply (Free 5 min, Pro 15 min).
 </ParamField>
 
+<ParamField body="compute" type="enum" default="auto">
+  Which machine class runs the job. One of `auto`, `cpu`, `gpu`.
+
+  - `auto` (default): a command using an NVENC or CUDA encoder, like `h264_nvenc`, routes to a GPU. Everything else runs on CPU. You don't set anything.
+  - `gpu`: force a GPU machine.
+  - `cpu`: force a CPU machine. A command that calls an NVENC encoder is rejected with `VALIDATION_ERROR`.
+
+  GPU jobs run the hardware encoders `h264_nvenc`, `hevc_nvenc`, and `av1_nvenc` on NVIDIA L4 GPUs, billed per second. `gpu` and `auto`-routed GPU jobs **require the Pro plan**; a GPU job on the Free plan returns `403 PLAN_LIMIT`. `cpu` and `auto` work on every plan.
+</ParamField>
+
 ## Response
 
 ```json