# Kuku TV & Kuku FM Episode Video Downloader API (`spider_studio/kuku-tv-episode-download-kvs`) Actor

Download Kuku TV (Kuku FM) episode videos by ID and store playable MP4 files with JSON sidecars in the run's Apify Key-value store. Export via API or Dataset.

- **URL**: https://apify.com/spider_studio/kuku-tv-episode-download-kvs.md
- **Developed by:** [Tarique](https://apify.com/spider_studio) (community)
- **Categories:** Automation, Social media, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 successful video uploads

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Kuku TV episode video downloader API to KVS

**Kuku TV & Kuku FM Episode Video Downloader API** is a **Kuku TV video downloader** for [Kuku FM](https://kukufm.com/) audio series and short-drama reels. Submit up to 1,000 episode IDs and receive playable MP4 files plus JSON metadata sidecars stored directly in the run's Apify Key-value store.

Each episode is resolved through an **Indian residential proxy**, while the video itself is downloaded **without a proxy** straight from the Kuku FM CDN. No Kuku FM account, login, or app installation is required.

### Why use this Kuku TV video downloader?

- Turn up to 1,000 Kuku TV `episodeId` values into playable MP4 files in a single run.
- Choose the rendition you want: `best`, `worst`, or an explicit label such as `1080p`, `720p`, `540p`, or `360p`.
- Get a `video-<episodeId>.mp4` file and a matching `meta-<episodeId>.json` sidecar for every episode.
- Verify every download: the Actor probes the produced file and rejects a truncated stream before it is charged.
- Keep proxy spend low: only the small API lookup uses the residential proxy — the heavy video bytes are fetched directly from the CDN.
- Store files in the run's default Key-value store, so no cloud-storage credentials are needed.

Typical use cases include **Kuku TV episode downloads**, Kuku FM offline archives, short-drama dataset assembly, media pipeline ingestion, and quality benchmarking across renditions.

### What does the downloader store?

Every successfully processed episode produces two Key-value store records:

| Record | Content type | Contents |
| --- | --- | --- |
| `video-<episodeId>.mp4` | `video/mp4` | The downloaded rendition, remuxed into a faststart MP4 with H.264 video and AAC audio. |
| `meta-<episodeId>.json` | `application/json` | Episode metadata, the video facts, the SHA-256 of the MP4, and the store location. |

Each Dataset row reports the outcome, so you can join a stored file back to its episode without opening the sidecar.

### How to download Kuku TV episodes

1. Open the Actor's **Input** tab.
2. Add one or more numeric episode IDs to `episodeIds`. The `episodes` array of the **Kuku TV & Kuku FM Show Details & Episodes API** lists every released `episodeId` for a show.
3. Pick a `quality`, or leave it at `best`.
4. Click **Start**.
5. Open the **Key-value store** tab for the MP4 files and the **Dataset** tab for the run report.

### How much does Kuku TV episode downloading cost?

FREE-tier users pay **$4.50 per 1,000 stored videos** ($0.0045 each). Users on BRONZE, SILVER, GOLD, PLATINUM, and DIAMOND tiers pay **$3.50 per 1,000** ($0.0035 each). One `video-uploaded` event is charged only after both the MP4 and its sidecar are stored, so a failed or skipped episode costs nothing.

There is no monthly result cap. Paid Apify platform usage for the run — compute, residential proxy traffic, and Key-value store storage — is billed separately by Apify. Storing large MP4 files is the dominant cost, so prefer a smaller `quality` when you do not need the largest rendition.

### Input

See the **Input** tab for all options. `episodeIds` accepts up to 1,000 numeric IDs; duplicates are ignored while their first-seen order is preserved.

```json
{
  "episodeIds": ["1685164", "1436319"],
  "quality": "best"
}
```

### Output

The Dataset reports one row per requested episode.

```json
{
  "episodeId": 1685164,
  "success": true,
  "showId": 282775,
  "title": "Episode 1",
  "index": 1,
  "seasonNo": 1,
  "durationSeconds": 134,
  "isPremium": true,
  "isLocked": false,
  "requestedQuality": "360p",
  "width": 360,
  "height": 640,
  "videoCodec": "h264",
  "fileSizeBytes": 3324590,
  "videoSha256": "ed5f114f8b8608a9d0a47528c001a263b78b427935d6f106d0d2938fe733e080",
  "playlistSegments": 34,
  "keyValueStoreId": "default",
  "videoKey": "video-1685164.mp4",
  "metaKey": "meta-1685164.json",
  "videoUrl": "https://api.apify.com/v2/key-value-stores/.../records/video-1685164.mp4",
  "error": null
}
```

An episode that fails produces a single uncharged row with `success: false` and an `error` message. Failures never leave a partial file in the Key-value store.

### Kuku TV episode download use cases

- Build an offline archive of a Kuku FM show from its episode IDs.
- Ingest Kuku TV short dramas into a media pipeline or editing workflow.
- Compare renditions by downloading the same episode at `360p` and `1080p`.
- Feed transcribed or analyzed video into research datasets.
- Keep proxy spend low by letting the video bytes bypass the residential proxy.

### Related Kuku TV Actors

| Actor | Purpose |
| --- | --- |
| [Kuku TV & Kuku FM Show Search Scraper API](https://apify.com/spider_studio/kuku-tv-search) | Discover shows and `showId` values by keyword, genre, or trope. |
| [Kuku TV & Kuku FM Show Details & Episodes API](https://apify.com/spider_studio/kuku-tv-series-detail) | Turn a `showId` into show metadata plus the full list of `episodeId` values to download. |
| [Kuku TV & Kuku FM Episode Details & Video URL API](https://apify.com/spider_studio/kuku-tv-episode-detail) | Inspect a single episode's metadata and its playable stream URL without downloading it. |
| [Kuku TV & Kuku FM Episode Comments Scraper API](https://apify.com/spider_studio/kuku-tv-episode-comments) | Export the public comments and listener profiles behind each episode. |

Also from the same publisher: [Hongguo short-drama Actors](https://apify.com/spider_studio/hongguo-video-download-kvs) for the Hongguo Duanju catalog.

### Frequently asked questions

#### Do I need a Kuku FM account to download an episode?

No. The episode endpoint used to resolve the video is public, and the CDN serves the media directly.

#### Why does only the resolution step use a proxy?

The API lookup benefits from an Indian residential address, while the CDN serves media from a global edge. Fetching the video bytes without a proxy is faster and avoids spending residential proxy bandwidth on the largest part of the transfer.

#### Which rendition does `best` pick?

`best` takes the largest rendition the master playlist advertises. Kuku TV episodes are portrait short dramas, so a rendition labelled `720p` is the 720x1280 stream and the label always tracks the shorter side. An explicit label picks that rendition, or the smallest one at least that large.

#### What happens if a download is truncated?

The Actor probes the produced MP4 and compares its runtime against the episode runtime. A file that is materially shorter is discarded, reported as a failed row, and never charged or stored.

#### Are the video files encrypted?

No. Kuku TV serves plain MPEG-TS HLS without content encryption, so the Actor remuxes the stream losslessly without re-encoding. If a future stream were encrypted, the Actor reports a clear failure rather than storing an unplayable file.

#### How many episodes download at once?

**Eight** by default, configured with `KUKU_MAX_CONCURRENCY` (1 to 20). Remuxing uses `-c copy`, so no transcoding happens and the CPU cost per stream is low; the practical ceiling is network bandwidth and Key-value store writes. Each finished file is deleted from local disk as soon as it is stored, so peak disk use is roughly the concurrency multiplied by the largest episode being downloaded. Lower the value when you download long episodes at `1080p`, and raise it for many short `360p` clips.

#### Can I download more than 1,000 episodes in one run?

Split larger sets across multiple runs or use the Apify API to start the Actor with several input batches.

### Legal use and support

Use the Actor lawfully and respect Kuku FM's terms, copyright, rate limits, privacy rules, and applicable law. Download only content you are authorized to store, and handle stored media in line with the rights of its owners.

Use the **Issues** tab for support and the **API** tab for generated integration examples.

# Actor input Schema

## `episodeIds` (type: `array`):

Numeric Kuku TV episode IDs to download. The fastest source is the `episodes` array of the Kuku TV Show Details & Episodes Actor. Duplicates are ignored while order is preserved.

## `quality` (type: `string`):

Which rendition to download. `best` takes the largest available, `worst` the smallest, and an explicit height such as `1080p` picks that rendition or the next one up. Kuku TV episodes typically offer 360p, 540p, 720p and 1080p.

## Actor input object example

```json
{
  "episodeIds": [
    "1685164",
    "1436319"
  ],
  "quality": "best"
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `keyValueStore` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "episodeIds": [
        "1685164",
        "1436319"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("spider_studio/kuku-tv-episode-download-kvs").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "episodeIds": [
        "1685164",
        "1436319",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("spider_studio/kuku-tv-episode-download-kvs").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "episodeIds": [
    "1685164",
    "1436319"
  ]
}' |
apify call spider_studio/kuku-tv-episode-download-kvs --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,spider_studio/kuku-tv-episode-download-kvs"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/IdcOB4yBDkcDkZlQm/builds/AQ4a6JmCOvnFstX3L/openapi.json