--- type: AI Model id: video-frame-api title: Video Frame Extractor API provider: Pixazo description: "Grab a single frame from a video as a PNG. Send position as a number of seconds from the start, or omit it to get the last visible frame. Seeking is done after decode, so the frame you get is the frame at that timestamp rather than the nearest keyframe." resource: https://www.pixazo.ai/models/video-frame-api docs_url: https://www.pixazo.ai/models/video-frame-api latest_version: v1 tags: - video-frame-extractor - pixazo variants: - id: media-extract-frame-v1 name: Video Frame Extractor 1.0 version: 1.0 capabilities: - Extract Frame timestamp: 2026-08-25T08:44:38.582Z --- # Video Frame Extractor API > Provider: **Pixazo** > Source: https://www.pixazo.ai/models/video-frame-api Grab a single frame from a video as a PNG. Send position as a number of seconds from the start, or omit it to get the last visible frame. Seeking is done after decode, so the frame you get is the frame at that timestamp rather than the nearest keyframe. ## Video Frame Extractor 1.0 ### Extract Frame ## Base URL ``` https://gateway.pixazo.ai/media-tools/v1/video-extract-frame ``` ## Authentication All requests require an API key passed via header. **Pricing:** Billed at **$0.002 per second of source video** — the length of the video you send. A 30-second source costs $0.06. **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 Frame Extractor generate request ## Request Code HTTP Python JavaScript cURL ``` POST https://gateway.pixazo.ai/media-tools/v1/video-extract-frame 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", "position": 5 } ``` ``` import requests url = "https://gateway.pixazo.ai/media-tools/v1/video-extract-frame" 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", "position": 5 } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ``` const url = "https://gateway.pixazo.ai/media-tools/v1/video-extract-frame"; 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", "position": 5 }; 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-extract-frame" \ -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", "position": 5 }' ``` ## Output ``` { "request_id": "media-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "QUEUED", "polling_url": "https://gateway.pixazo.ai/v2/requests/status/media-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` [Try Now](https://api.pixazo.ai/api-details#api=media-tools&operation=video-extract-frame) ## 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 Frame Extractor generate request Parameter Required Type Default Allowed values / range Description video\_url Yes string — HTTP(S) URL to an MP4 or MOV; ≤ 500 MB, ≤ 600 s Publicly reachable HTTP(S) URL of the source video. position No number — (the last visible frame) 0 – 86400 Seconds from the start, as a JSON **number**. A quoted string is rejected. Must sit inside the source — a position past the end fails rather than clamping. Omit it to get the final frame. The output is a **PNG**, not a video. Seeking happens after decode, so you get the frame at that timestamp rather than the nearest keyframe. A position past the end of the video is an error, not a clamp. ## Example Request ``` { "video_url": "https://api-assets.pixazo.ai/media-api-test/t.mov", "position": 5 } ``` ## Response ``` { "request_id": "media-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "QUEUED", "polling_url": "https://gateway.pixazo.ai/v2/requests/status/media-extract-frame_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-extract-frame' not found or is disabled" } ``` ### Error via Status/Webhook ``` { "request_id": "media-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "ERROR", "model_id": "media-extract-frame", "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-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ``` ## Response (Completed) ``` { "request_id": "media-extract-frame_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "COMPLETED", "model_id": "media-extract-frame", "error": null, "output": { "media_url": [ "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/media-extract-frame_019dxxxx/output.png" ], "media_type": "image/png" }, "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.