FreeReels API — Free Actor, Your Ezvid API Key

Run FreeReels content requests through Ezvid as an Apify Actor and export results to a dataset. Version 2.0 uses a bundled OpenAPI snapshot from 2026-10-10 covering the 10 FreeReels GET endpoints exposed by Ezvid.

Register with Ezvid and use your own API key. The intended Store model is a free Actor with no developer fee, configured as pay per usage in Apify Console. Apify compute/storage/network usage and Ezvid API access/quota are separate and depend on your accounts. The code contains no custom charging calls. Deploying it does not change an existing Actor's pricing; follow DEPLOY.md.

Get started

1. Register with Ezvid and obtain your own API key. Start with the Ezvid API documentation for API access information. If key issuance is not available there, request access from Ezvid's operator. This Actor does not create Ezvid accounts or issue keys.
2. Enter that key in the required Your registered Ezvid API key input field.
3. Choose an action/resource, then run the Actor.

Start with a small languages request to verify your key:

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "action": "langs"
}

Replace the placeholder with your key in the Apify input form. Open the run's Results output for dataset records and Run summary for the OUTPUT record. Use home, tabs, trending or search to obtain IDs before requesting content details or episodes.

The apiKey field uses Apify's encrypted secret input. Every API request sends it only in X-API-Key. Missing/blank keys fail before any HTTP request; Ezvid validates the supplied key and its permissions. There is no embedded key and no EZVID_API_KEY environment fallback. Authentication errors do not include upstream bodies or keys in logs. Local INPUT files contain plaintext secrets: keep them in the ignored storage/ directory.

Supported resources

See RESOURCES.md for the complete generated reference, including all required path arguments and native query parameters.

Coverage includes languages, home, tabs, tab index, for-you feed, hot words, trending, search, series detail and full episode lists. Every FreeReels resource in the bundled contract is reachable through action or resource.

Use action for the common shortcuts below, or pass the exact relative path template, such as detail/{id} or tab/{id}, in resource. A full /api/freereels/... template is also accepted. Arbitrary URLs are not accepted.

For convenience, action supports these familiar aliases:

• home: resolves to FreeReels home.
• detail / episodes: resolves to the documented detail/{id} and episodes/{id} routes.
• languages / langs: resolves to the documented langs endpoint.
• hot: resolves to hotwords (the documented search hot-words endpoint).
• categories: resolves to tabs (the home tabs endpoint).
• tab resolves to tab/{id} when id (or pathParams.id) is supplied.

Unsupported or ambiguous actions fail with a request to select an exact resource.

Input

Field	Purpose
apiKey	Required, your own registered Ezvid key; no default/shared key.
action	Convenience action; defaults to home.
resource	Exact resource template; overrides action.
pathParams	Object containing native path arguments; overrides id/ep.
queryParams	Object containing native query arguments; overrides shortcuts. Unknown keys fail validation.
id	Shortcut for the first path parameter (detail/{id}, tab/{id}, episodes/{id}).
ep	Shortcut for the episode/chapter parameter. May be an opaque ID, not a sequence number.
query	Search text, mapped to q.
language	Mapped to language; omit for upstream default.
category	Sent when the endpoint documents category.
cursor	Starting opaque cursor for supported endpoints.
maxPages	1–50, default 1; maximum page fetches for a paginated resource. Retries are additional HTTP attempts.
pagination	auto (default), none, or cursor. FreeReels does not document page/p.
outputMode	records (default) or response.

Optional shortcuts are sent only where supported. Use queryParams for strict parameter checking and provider-specific options such as limit.

Search FreeReels

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "action": "search",
  "query": "love",
  "language": "en"
}

Fetch FreeReels series detail

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "action": "detail",
  "id": "YOUR_SERIES_ID"
}

Fetch FreeReels episodes for a series

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "action": "episodes",
  "id": "YOUR_SERIES_ID"
}

Paginate FreeReels trending

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "action": "trending",
  "language": "en",
  "cursor": "YOUR_OPAQUE_CURSOR",
  "maxPages": 5
}

Load a FreeReels tab by id

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "resource": "tab/{id}",
  "pathParams": { "id": "YOUR_TAB_ID" }
}

Pagination and output

Auto pagination prefers an explicit cursor input. If absent, the resource's cursor parameter is used and the Actor stops on hasMore: false/hasNext: false or a missing/repeated token. Endpoints without cursor run once. The Actor does not invent cursor values or silently switch to another resource.

The default dataset contains records with _meta (provider, resource, page, url, fetchedAt). Records mode unwraps common data/result/payload envelopes and list arrays. Entity/detail objects retain nested episodes; primitive values are wrapped in { "value": ... }.

Home responses containing several collections (for example FreeReels home with tabs, shelves and featured titles) remain a single object so none of those sections are discarded. A dataset record is not necessarily one movie.

Provider fields are preserved rather than normalized to a universal movie schema. Ezvid's OpenAPI does not describe response field schemas. For an unfamiliar resource or to preserve all envelope metadata, use outputMode: "response", which stores { "response": <complete JSON>, "_meta": ... } for each nonempty page.

The OUTPUT key-value record contains provider, resource, pagination, outputMode, pagesFetched, recordsPushed, maxPages, stopReason, timestamps, and continuation values (nextCursor when maxPages is reached). pagesFetched counts parsed responses, including a final empty or repeated page; it does not count retry attempts. Pass nextCursor as input cursor to continue with the same resource and filters. A later failure fails the run; previously written dataset records remain, but a success summary is not written.

Requests time out after 60 seconds. Network errors, HTTP 429 and 5xx get up to three retries, with backoff and Retry-After handling capped at 60 seconds. 401/403 and other client errors fail immediately. The Actor returns metadata and playback URLs; it does not download or stream video. Playback URLs may expire.

Verification and availability

On 2026-10-10, all 33 automated tests passed on Node.js 22 and the Apify input schema passed CLI validation. Tests cover request construction for all 10 FreeReels endpoints, authentication requirements, parsing, pagination, retries and the Apify SDK lifecycle with mocked HTTP responses.

Live checks using a registered key covered the FreeReels home request, which returned 2 records. Additional resources can be exercised live once a key is supplied. These counts describe the test run, not a permanent availability guarantee. All 10 endpoints were checked against the contract, but not all were called live.

See LIVE_CHECKS.md for the live check record. An unavailable home resource does not necessarily mean every resource of that provider is down. Ezvid can wrap provider errors as HTTP 400; the Actor reports those separately from ordinary request validation errors.

Development

Use Node.js 22+ and, for apify run/deployment, the Apify CLI.

npm ci
npm test
npm run validate:input

Create the local input directory:

$mkdir -p storage/key_value_stores/default

Save one of the input examples above as storage/key_value_stores/default/INPUT.json, replacing the key placeholder locally. Then run npm start (Apify SDK storage) or npm run start:local (Apify CLI). The storage/ directory is ignored by Git.

Local results are written to storage/datasets/default/; the summary is at storage/key_value_stores/default/OUTPUT.json. These paths assume the default local storage configuration. Back up results before starting another local run, because the SDK purges default storage on startup while preserving input.

Command	Purpose
npm start	Run src/main.js through the Apify SDK.
npm run start:local	Run through the installed Apify CLI.
npm test	Run automated tests; no real Ezvid key or API requests required.
npm run validate:input	Validate the input schema using the installed CLI.
npm run generate	Regenerate the resource reference from the bundled snapshot.
npm run sync:resources	Download the public Ezvid OpenAPI, filter to FreeReels, and regenerate.
npm run deploy	Deploy with apify push; requires Apify login.

npm run sync:resources   # download the public contract, filter to FreeReels, refresh reference
npm test
npm run validate:input

Resource changes are reviewed at build time; each Actor run uses the checked-in snapshot. Updating the snapshot does not prove every resource is available: end-to-end verification requires a valid key with access to those resources.

See DEPLOY.md to publish a free/pay-per-usage Actor.

License

MIT.