Drama & Short Video API

Search, browse, and download drama episodes from multiple providers through one unified REST API. Built for developers.

DramaBox Blink StoryReel VibeShort NetShort DramaWave

How to use the API Getting Started

Get up and running in minutes. Register for a free API key, then start making requests.

Register & Get Your Token

Create an account via POST /auth/register or contact admin for a higher-tier account. You'll receive an API token — save it immediately, it's shown only once.

Authenticate Requests

Include your token in every request header:
Authorization: Bearer mk_xxxxxxxxxxxxxxx

Search & Discover

Use GET /v1/search with a provider and keyword to find dramas. Check GET /v1/providers to see which providers are available.

Get Episode Details & Videos

Fetch episode info with GET /v1/drama/{provider}/{bookId}/episodes/{ep}. The processed MP4 is served at the downloadUrl included in the response.


Three methods supported Authentication

Choose the method that fits your integration.

API Token Recommended

Register to get a mk_ prefixed token. Send it as a Bearer token in the Authorization header. Best for server-to-server integrations.

curl -H "Authorization: Bearer mk_abc123..." \
  https://your-host/v1/providers

RapidAPI Marketplace

Subscribe on RapidAPI to get automatic authentication via proxy headers. No token management needed — RapidAPI handles it.

Session Token Admin

Login via POST /auth/login to get a session token (ses_ prefix). Used by the admin panel. Expires after 24 hours.


All endpoints API Reference

Base URL: https://your-host — all responses are JSON unless noted.

GET /v1/providers List available providers ▼

Description

Returns the list of drama providers currently configured and available on the server.

Example Response

{
  "providers": ["dramabox", "storyreel", "dramawave"]
}
GET /v1/search?provider={provider}&keyword={keyword} Search dramas ▼

Parameters

NameTypeRequiredDescription
providerstringrequiredProvider name (e.g. dramabox)
keywordstringrequiredSearch keyword (1–200 chars)
pageintoptionalPage number (default: 1)

Example Response

{
  "provider": "dramabox",
  "movies": [
    {
      "bookId": "123456",
      "bookName": "Love in the Moonlight",
      "coverUrl": "https://cdn.example.com/cover.jpg",
      "introduction": "A romantic drama about...",
      "chapterCount": 80,
      "source": "dramabox"
    }
  ],
  "page": 1,
  "hasMore": true
}
GET /v1/drama/{provider}/{book_id} Drama details & episode list ▼

Parameters

NameTypeRequiredDescription
providerstringrequiredProvider name
book_idstringrequiredDrama ID (numeric or alphanumeric)

Example Response

{
  "provider": "dramabox",
  "bookId": "123456",
  "bookName": "Love in the Moonlight",
  "coverUrl": "https://cdn.example.com/cover.jpg",
  "introduction": "A romantic drama about...",
  "chapterCount": 80,
  "episodes": [
    {
      "episode": 1,
      "chapterId": "78901",
      "chapterName": "EP 1",
      "thumbnailUrl": "https://cdn.example.com/ep1.jpg",
      "locked": false
    }
  ]
}
GET /v1/drama/{provider}/{book_id}/episodes/{ep} Episode detail + trigger video processing ▼

Parameters

NameTypeRequiredDescription
providerstringrequiredProvider name
book_idstringrequiredDrama ID
episodeintrequiredEpisode number (≥ 1)

Example Response

{
  "provider": "dramabox",
  "episode": 1,
  "chapterId": "78901",
  "chapterName": "EP 1",
  "thumbnailUrl": "https://cdn.example.com/ep1.jpg",
  "locked": false,
  "downloadUrl": "/v1/videos/dramabox/123456/1",
  "fileSize": 15728640,
  "movie": {
    "bookId": "123456",
    "bookName": "Love in the Moonlight"
  }
}
// FREE tier: episodes 1–5 only, no download
// BASIC+: all episodes, full download access
GET /v1/videos/{provider}/{book_id}/{ep} Stream/download processed MP4 ▼

Parameters

NameTypeRequiredDescription
providerstringrequiredProvider name
book_idstringrequiredDrama ID
episodeintrequiredEpisode number

Response

Returns video/mp4 file directly, or 302 Redirect to CloudFront/S3 presigned URL when S3 storage is enabled. Call GET .../episodes/{ep} first to trigger processing.

Errors

StatusReason
403FREE tier — download not allowed
404Video not processed yet
POST /auth/register Create account & get API token ▼

Request Body

FieldTypeRequiredDescription
emailstringrequiredValid email address
passwordstringrequiredMin 8 characters
display_namestringoptionalDisplay name

Example

curl -X POST https://your-host/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "securepass123",
    "display_name": "John"
  }'

Example Response

{
  "user_id": "a1b2c3d4-...",
  "email": "dev@example.com",
  "tier": "FREE",
  "token": "mk_abc123def456...",
  "message": "Save this token — it cannot be shown again."
}
// ⚠ The token is shown ONCE. Store it securely.
POST /auth/login Login & get session token ▼

Request Body

FieldTypeRequiredDescription
emailstringrequiredRegistered email
passwordstringrequiredAccount password

Example Response

{
  "user_id": "a1b2c3d4-...",
  "email": "dev@example.com",
  "display_name": "John",
  "role": "user",
  "tier": "FREE",
  "session_token": "ses_abc123..."
}

Common status codes Error Handling

All errors return JSON with an error field.

StatusMeaningAction
400Provider not availableCheck /v1/providers
401Missing or invalid credentialsCheck your token or register
403Tier restrictionUpgrade tier or contact admin
404Not foundCheck IDs / process episode first
409Email already registeredLogin instead or use another email
422Validation errorCheck request params
429Rate limit exceededWait and retry (see Retry-After header)
502Upstream provider errorRetry later or try another provider

Plans & limits Access Tiers

New registrations start at FREE. Contact admin to upgrade.

FREE

Self-register
  • Search all providers
  • Browse drama details
  • Episodes 1–5 only
  • No video download
  • 0.5 req/s, burst 3

BASIC

Contact admin
  • All episodes
  • Video download
  • 1 req/s, burst 5
  • 2 concurrent jobs

PRO

Contact admin
  • All episodes
  • Video download
  • 5 req/s, burst 20
  • 5 concurrent jobs

ULTRA

Contact admin
  • All episodes
  • Video download
  • 20 req/s, burst 60
  • 10 concurrent jobs

Get your API key now Register

Create a free account to start using the API immediately.

Create Account


Get in touch Contact

Need help or want to upgrade?

Reach out to the admin for tier upgrades, custom rate limits, enterprise plans, or any questions about the API.

Or register first, then email us your registered email to request a tier upgrade.