DramaBox API Actor

A single-provider fork of ezvidnet/short-drama-api. Wraps the Ezvid Movies API Gateway and exposes only the DramaBox endpoints behind a small, cursor-paginated interface.

The upstream actor supports 15 providers. This Actor is hard-coded to DramaBox — simpler input schema, smaller surface area, easier to publish as a free/cheap public Actor.

Endpoints

Action	Upstream	Pagination	Required input
home	GET /api/dramabox/home	cursor	—
categories	GET /api/dramabox/categories	cursor	—
latest	GET /api/dramabox/latest?page=N	page-based	—
vip	GET /api/dramabox/vip	cursor	—
search	GET /api/dramabox/search?q=...	cursor	query
detail	GET /api/dramabox/detail/{id}	cursor	id
episodes	GET /api/dramabox/episodes/{id}	cursor	id

All endpoints require an X-API-Key header.

Output

Each upstream record is enriched with a _meta block:

{
  "id": "abc123",
  "title": "Sample Drama",
  "poster": "https://cdn.ezvid.net/posters/abc123.jpg",
  "stream": "https://stream.ezvid.net/hls/abc123/master.m3u8",
  "_meta": {
    "provider": "dramabox",
    "action": "home",
    "page": 1,
    "url": "https://api.ezvid.net/api/dramabox/home?limit=20",
    "fetchedAt": "2026-08-21T07:40:01.123Z"
  }
}

A run summary is also written to the OUTPUT key-value store with counts and timestamps.

Quick examples

1. Pull 50 latest home records

{ "action": "home", "limit": 50, "maxPages": 1 }

2. Search DramaBox for "revenge"

{ "action": "search", "query": "revenge", "limit": 20, "maxPages": 1 }

3. Detail for a specific drama

{ "action": "detail", "id": "abc123" }

4. Full episode list

{ "action": "episodes", "id": "abc123" }

5. Page-based latest feed (walk 5 pages)

{ "action": "latest", "page": 1, "maxPages": 5 }

6. VIP feed, Indonesian language

{ "action": "vip", "language": "id", "limit": 20, "maxPages": 3 }

Authentication

The Actor calls Ezvid's API with an X-API-Key header.

• Bring your own key — paste your Ezvid key into the apiKey input.
• Built-in key (pay-per-result) — leave apiKey blank and set EZVID_API_KEY in the Actor's Settings → Environment variables. When you publish on Apify Store, users without their own key can still run the Actor and the upstream cost comes out of your account.

Sign up for a key at https://api.ezvid.net/.

Input

Field	Type	Default	Notes
action	enum	home	One of: home, categories, latest, vip, search, detail, episodes
query	string	—	Required for search
id	string	—	Required for detail, episodes
language	string	—	Optional. See /api/dramabox/langs
category	string	—	Optional category scope
page	integer	1	Starting page for latest
limit	integer	20	Page size, 1–100
maxPages	integer	1	Pages to walk, 1–50
apiKey	string	—	Your Ezvid key (overrides built-in)

Local development

Requirements: Node 20+, npm.

# Install
npm install

# Set your key
cp .env.example .env
# then edit .env and set EZVID_API_KEY

# Run with the bundled input fixture
npm start

The Actor reads input from storage/key_value_store/INPUT.json when run locally via the Apify CLI:

# Optional: install the Apify CLI and run with its local runtime
npx apify run

Deploying to Apify

# 1. Login (one-time)
npx apify login

# 2. Push — auto-creates the Actor on the platform using the name
#    in .actor/actor.json ("dramabox-api")
npx apify push

# 3. In the Apify Console (https://console.apify.com):
#    - Open "dramabox-api"
#    - Settings → Environment variables → add EZVID_API_KEY=<your key>
#      (skip if you want every run to bring its own key)
#    - Publication → "Publish" → fill the public listing from this README

The CLI has no apify actors create command. apify push is the command that both creates the Actor (if it doesn't exist) and uploads the source.

Pricing (suggestion)

On Apify Store you can set pay-per-event pricing so users pay only for records they actually pull:

Event	Suggested price
Actor start	$0.001
Record returned	$0.0005 – 0.002

The built-in key is billed to the Actor, not to the end user.

Limits & caveats

• Upstream API may rate-limit. The Actor retries 429 / 5xx up to 3 times with exponential backoff. If you still hit a limit, lower maxPages or run in smaller batches.
• The Ezvid API is not affiliated with the upstream drama providers — make sure your use case complies with their terms.
• The Actor returns metadata + HLS URLs only; playback is the consumer's job.

Differences vs ezvidnet/short-drama-api

Area	Upstream	This fork
Providers	15 (dramawave, reelshort, …)	1 (dramabox)
provider input	required enum	dropped
ep / locale	used by watch, source on other providers	unused (no watch / source actions)
Built-in key	hard-coded master key for pay-per-result	empty by default — bring your own
Dependencies	apify only	apify only

License

MIT.