Docs › Test mode
Test mode
Try the whole API without paying for it or touching your real videos, like test keys in a payments API. A test key works exactly like an API key, but everything it makes is a test video: free, small (one MP4, 480p, a minute), marked, and deleted after a day. Test mode is on every plan, including Free.
Test keys
Create one in the app (Account → API keys → Create test key) or with POST /account/keys {"mode": "test"} from a signed-in session. A test key starts with vp_test_ (live keys start with vpk_) and is used the same way, as a bearer token on the same base URL. You can have 5 active test keys, and they don't use your plan's API key allowance. In GET /account/keys each key has a mode of live or test.
Upload tokens and edit tokens made with a test key are test-mode too, so a browser using one makes test videos. In the web app, the Test mode switch in the sidebar does the same for your signed-in session: it lists and makes test videos until you switch back. (A session sends X-Video-Piper-Mode: test; an API key can't switch, because the key decides.)
What is different
| Test mode | |
|---|---|
| Separate from live | A test key only sees test videos, and a live key never sees them: GET /videos, status, reprocess, delete and edits all answer 404 NOT_FOUND for the other mode's videos. Videos have "mode": "test" (or "live") in the list and in status. |
| Free | Never metered or billed: no processing minutes, storage or delivery are counted, GET /usage is empty in test mode, and no overage applies. Every plan feature (captions, redaction, screen + camera, streaming) is available. |
| Short and small | One MP4 of at most 60 seconds and 480p, with no streaming (HLS) copies; sources up to 2 GB. Asking for more is not an error: a higher maxHeight or streaming is clamped to 480p and one MP4, and effective in the video's status says what it was made with. Only a request that can't be clamped is refused with 403 TEST_LIMIT before anything starts: a durationSeconds above 60, a trim or edit known to be longer than 60 seconds, or a larger file. When the length isn't known up front (a recording, a URL import), the first 60 seconds are processed. |
| Daily quota | By your plan, per rolling 24 hours per account: 5 test videos on Free (or with no plan), 20 on Starter, Pro and Scale. Uploads, edits and reprocesses each count, separately from your live daily limit. Over it: 429 TEST_LIMIT, naming the limit and your plan. Captions are allowed and don't count extra. |
| Marked | A small TEST mark is burned into the top-left corner of every output (the download, the streaming renditions, the poster and thumbnails). It can't be turned off or redacted away. |
| Temporary | A test video, its original upload and its work files are deleted about 24 hours after it was made, by the same removal as DELETE /videos/{id}. Status shows deletesAt (Unix time). A video.deleted webhook is sent with reason: "test_expired". |
| Not available | A test key can't read or change the account, its profile or its webhook (403 TEST_LIMIT; sign in for those), and test videos can't be embedded. |
| Processing | Test videos go to the standard queue, never ahead of paying customers' work, and always encode on CPU. |
Webhooks in test mode
Every webhook event now has a livemode field: false for events about test videos, true for live ones. Test events are sent to the same endpoint as live events; check livemode to tell them apart (and ignore or route test events as you like).
{
"id": "evt_a1b2c3d4e5f6g7h8",
"type": "video.ready",
"livemode": false,
"createdAt": "2026-10-09T14:30:45Z",
"data": { "videoId": "3f1c…", "fileName": "demo.mp4", … }
}Moving to live
Nothing else changes: swap the test key for a live key. Videos made before test mode existed are live. Test videos can't be promoted; make the video again with a live key.