DramaBox API — Free Actor, Your Ezvid API Key

Run Ezvid DramaBox content requests as an Apify Actor and export results to a dataset. Version 1.0.0 uses a bundled OpenAPI snapshot from 2026-10-10 covering 1 provider (DramaBox) and 10 GET endpoints.

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",
  "provider": "dramabox",
  "action": "languages"
}

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 browse, search, or another discovery resource 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 query parameters.

Provider: dramabox (10 resources).

Coverage includes languages, lists, discovery, search, categories, details, episodes, playback sources, subtitles and other resources actually exposed by DramaBox. The service routes /, /health, /openapi.json are not content resources.

Use provider: "dramabox" with resource to address any endpoint. Supply the exact relative path template, such as allepisode (the DramaBox episodes alias), or a full /api/dramabox/... template. Arbitrary URLs are not accepted.

For convenience, action supports exact resource names and these familiar aliases:

• home: resolves to DramaBox foryou.
• detail / episodes: DramaBox uses bookId query endpoints (detail → detail?bookId=..., episodes → allepisode?bookId=...).
• languages / langs: resolves to languages.
• source: resolves to a unique episode source endpoint when available.
• DramaBox vip/categories are no longer advertised: those paths are absent from the current Ezvid contract.

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.
provider	Required, fixed to dramabox.
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, or DramaBox bookId.
ep	Shortcut for the episode/chapter parameter. May be an opaque ID, not a sequence number.
query	Search text, mapped to query.
language	Mapped to lang; omit for upstream default.
category	Sent when the endpoint documents category.
limit	1–100, default 20; sent only if documented and may be capped upstream.
page	Starting numeric page, used by browse/dubbed.
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, cursor, or page.
outputMode	records (default) or response.

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

Search DramaBox

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

Fetch DramaBox episodes

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "dramabox",
  "action": "episodes",
  "id": "YOUR_DRAMA_ID"
}

Browse dubbed DramaBox content starting at page 5

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "dramabox",
  "resource": "dubbed",
  "language": "en",
  "queryParams": { "classify": "terbaru" },
  "page": 5,
  "maxPages": 3
}

Pagination and output

Auto pagination uses an explicitly supplied cursor, otherwise the endpoint's page/p, otherwise its cursor. Endpoints without these parameters run once. The Actor stops on empty results, end markers, repeated pages/tokens, missing next cursor, or maxPages. It 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": ... }.

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/nextPage when maxPages is reached). pagesFetched counts parsed responses, including a final empty or repeated page; it does not count retry attempts. A numeric next page is a candidate if the upstream did not supply an explicit next-page marker. Pass nextCursor as input cursor, or nextPage as input page, 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 provider availability

Automated tests cover request construction for all 10 DramaBox endpoints, authentication requirements, parsing, pagination, retries and the Apify SDK lifecycle with mocked HTTP responses. See the test suite in tests/.

Live checks using a registered key have covered DramaBox languages, search, browse, detail, episodes, plus a home request. Some home responses were empty or returned upstream failures; detail, search, browse and episodes worked even when home failed. These counts describe a specific test run, not a permanent availability guarantee.

See LIVE_CHECKS.md for findings. An unavailable home resource does not necessarily mean every resource 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 OpenAPI snapshot and regenerate the reference. Note: the sync tool keeps the upstream catalog untouched; this repo is filtered to DramaBox only, so a fresh sync must be filtered again before being checked in.
npm run deploy	Deploy with apify push; requires Apify login.

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 endpoint 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.