# Hongguo Full Series Downloader & Video Decryption API (`spider_studio/hongguo-series-download-kvs`) Actor

Bulk-download and decrypt every episode from Hongguo short drama series IDs. Save playable MP4 videos, metadata, and signed links directly to Apify KVS.

- **URL**: https://apify.com/spider\_studio/hongguo-series-download-kvs.md
- **Developed by:** [Tarique](https://apify.com/spider_studio) (community)
- **Stats:** 1 total users, 0 monthly users, 57.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 successful kvs 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

### Hongguo full series video downloader and decryption API

**Hongguo Full Series Downloader & Video Decryption API** bulk-downloads every episode from one or more authorized [Hongguo Duanju](https://hongguoduanju.com/) short drama series. Submit numeric `seriesIds`; the Actor discovers each complete episode list, selects the best available rendition, decrypts every supported video into a playable MP4, and stores the MP4 plus redacted metadata in **Apify Key-value store (KVS)**.

This Actor is built for full-series workflows. It removes the manual step of looking up every episode `videoId`, needs no S3-compatible bucket, and returns signed KVS links that can be used from the Apify API, schedules, webhooks, Make, n8n, or another Actor.

Use it only for Hongguo content that you own or are explicitly authorized to download, decrypt, store, and process.

### Why use this Hongguo full-series downloader?

- Submit up to 1,000 unique Hongguo `seriesIds` in one run.
- Resolve multiple series and download their episodes with bounded concurrency.
- Automatically select the best available quality for each episode.
- Produce actual playable MP4 files instead of temporary encrypted CDN URLs.
- Store videos and redacted JSON metadata directly in Apify KVS.
- Return one Dataset row per episode with series title, episode order, quality, signed links, file size, and SHA-256.
- Isolate series and episode failures so available videos can still finish.
- Retry temporary upstream failures with exponential backoff.

Common use cases include authorized short-drama archiving, transcription preparation, subtitle workflows, internal media analysis, moderation, and automated full-series processing.

### Which Hongguo video downloader should I use?

Choose by input type and storage destination. This keeps full-series downloads separate from the two per-episode video download options.

| Goal | Actor | Input | Destination |
| --- | --- | --- | --- |
| Download every episode from one or more series | **[Hongguo Full Series Downloader & Video Decryption API](https://apify.com/spider_studio/hongguo-series-download-kvs)** | `seriesIds` | Apify KVS |
| Download selected episodes without configuring a bucket | [Hongguo Video Downloader API to KVS](https://apify.com/spider_studio/hongguo-video-download-kvs) | `videoIds` | Apify KVS |
| Deliver selected episodes to long-term cloud storage | [Hongguo Video Downloader & Decryption API](https://apify.com/spider_studio/hongguo-video-download) | `videoIds` plus storage settings | S3, OSS, COS, or compatible storage |

### What data does the Hongguo series downloader return?

| Field | Type | Description |
| --- | --- | --- |
| `seriesId`, `seriesTitle` | string | Requested Hongguo series and resolved title. |
| `episodeIndex`, `episodeTitle` | string | Episode order and title when available. |
| `videoId` | string | Video ID discovered from the episode list. |
| `success`, `error` | boolean/string | Per-episode processing status and safe failure message. |
| `definition`, `width`, `height`, `codec` | mixed | Selected and validated media properties. |
| `videoRecordKey`, `metaRecordKey` | string | Stable KVS keys for the MP4 and JSON metadata. |
| `videoUrl`, `metaUrl` | string | Signed links for retrieving the KVS records. |
| `fileSize`, `sha256` | integer/string | MP4 size and integrity digest. |

Temporary source URLs, content keys, decryption envelopes, cookies, and signing data are excluded from public results.

### How to download every episode of a Hongguo short drama

1. Find one or more numeric series IDs with the [Hongguo Search API](https://apify.com/spider_studio/hongguo-search), [Recommendation Feed API](https://apify.com/spider_studio/hongguo-recommend-feed), or another authorized source.
2. Open this Actor's **Input** tab.
3. Replace the prefilled example and add the IDs to `seriesIds`.
4. Click **Start**. The Actor resolves each series and processes all discovered episodes.
5. Open **Output → Episode files** to browse MP4 and metadata records, or read `videoUrl` from Dataset.

Successful episodes use stable KVS record names:

```text
video-{seriesId}-episode-{episodeIndex}-{videoId}.mp4
meta-{seriesId}-episode-{episodeIndex}-{videoId}.json
```

### How much does a Hongguo full-series download cost?

The Actor charges only for successfully uploaded episode videos. Series resolution is included at no additional event charge.

| Event | When it is charged | FREE | BRONZE–DIAMOND |
| --- | --- | ---: | ---: |
| `video-uploaded` | Once after one episode MP4 and its metadata are both stored in KVS | $0.0045 per episode | $0.0035 per episode |

Failed series and failed episode uploads are not charged. Apify run spending limits are respected. Compute, residential proxy traffic, data transfer, KVS operations, and retained storage are charged separately as Apify platform usage.

Apify FREE-plan accounts can store up to **100 successful episodes per UTC calendar month** through this Actor. The Actor atomically reserves Upstash quota before starting media downloads, so concurrent runs cannot exceed the per-user monthly limit. Failed episode processing releases its reserved slot. Paid-plan accounts are not subject to this product quota.

### Input

The only public input is `seriesIds`, a required list containing 1–1,000 unique numeric Hongguo series IDs. The Apify Input tab includes a working `prefill` value so the form is ready to test; replace it with series IDs you are authorized to process.

```json
{
  "seriesIds": [
    "8000000000000000001",
    "8000000000000000002"
  ]
}
```

### Output

You can download the Dataset in various formats such as JSON, HTML, CSV, or Excel. The actual decrypted MP4 and JSON metadata files are stored in the run's default KVS.

```json
{
  "seriesId": "8000000000000000001",
  "seriesTitle": "Example Short Drama",
  "videoId": "7000000000000000001",
  "episodeIndex": "1",
  "episodeTitle": "Episode 1",
  "success": true,
  "definition": "1080p",
  "width": 1080,
  "height": 1920,
  "codec": "hevc",
  "keyValueStoreId": "AbCdEfGhIjKlMnOpQ",
  "videoRecordKey": "video-8000000000000000001-episode-1-7000000000000000001.mp4",
  "metaRecordKey": "meta-8000000000000000001-episode-1-7000000000000000001.json",
  "videoUrl": "https://api.apify.com/v2/key-value-stores/AbCdEfGhIjKlMnOpQ/records/video-example.mp4?signature=...",
  "fileSize": 17080494,
  "sha256": "f7db5d68490b3080fe35fbff46dfc425d1967bd0de9c0bead8b164ec9bbc838e",
  "error": null
}
```

### Hongguo full-series downloader API integration

Actor page: [Hongguo Full Series Downloader & Video Decryption API](https://apify.com/spider_studio/hongguo-series-download-kvs)

Start an asynchronous run with the stable Actor name:

```bash
curl -X POST \
  'https://api.apify.com/v2/acts/spider_studio~hongguo-series-download-kvs/runs' \
  -H 'Authorization: Bearer YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"seriesIds":["8000000000000000001","8000000000000000002"]}'
```

The run response includes `defaultDatasetId` and `defaultKeyValueStoreId`. Open the Actor's **API** tab for Python, JavaScript, CLI, HTTP, OpenAPI, and MCP examples.

### Tips for reliable full-series video downloads

- Default concurrency is 8 and can be adjusted with the private `HONGGUO_MAX_CONCURRENCY` environment setting.
- Each episode is resolved immediately before download because upstream media references can expire.
- Increase Actor memory and disk capacity when downloading many large episodes concurrently.
- The Actor preserves supported source quality but does not upscale video.
- Default KVS retention follows the user's Apify storage settings.
- Use the [object-storage downloader](https://apify.com/spider_studio/hongguo-video-download) for permanent archives, lifecycle rules, versioning, or high-volume CDN delivery.
- Treat signed KVS record URLs as bearer links and share them only with authorized recipients.

### Related Hongguo short drama Actors

| Workflow | Actor | Use it for |
| --- | --- | --- |
| Discover titles | [Hongguo Short Drama Search API](https://apify.com/spider_studio/hongguo-search) | Find dramas and `seriesId` values by title, trope, or keyword. |
| Browse recommendations | [Hongguo Recommendation Feed API](https://apify.com/spider_studio/hongguo-recommend-feed) | Discover trending short dramas and their IDs. |
| Inspect episode directories | [Hongguo Series Details & Episodes API](https://apify.com/spider_studio/hongguo-series-detail) | Retrieve metadata and complete episode `videoId` lists without downloading media. |
| Resolve one best URL | [Hongguo Best Quality Video URL API](https://apify.com/spider_studio/hongguo-video-best) | Return the best available rendition and temporary media URL. |
| Compare every quality | [Hongguo All Video Qualities API](https://apify.com/spider_studio/hongguo-video-variants) | Inspect all resolutions, bitrates, codecs, and URLs. |

### Frequently asked questions

#### Can this Actor download multiple complete Hongguo series?

Yes. Add up to 1,000 unique `seriesIds`. The Actor resolves multiple series concurrently, combines their episode jobs, and preserves the owning `seriesId` in every Dataset row and KVS key.

#### Does KVS contain the actual decrypted videos?

Yes. Every successful `video-...mp4` record contains the playable decrypted MP4. Dataset provides a signed `videoUrl` for convenient retrieval.

#### What happens if one series or episode fails?

The Actor writes a safe failure row and continues processing available series and episodes. Set `HONGGUO_FAIL_ON_ERROR=true` when partial completion should make the run fail.

#### Are Hongguo videos stored permanently?

Not necessarily. Default KVS retention follows the user's Apify storage settings. Choose the object-storage downloader when you need permanent retention, bucket policies, versioning, or CDN delivery.

#### Can I download private or unauthorized content?

No. You must own the content or have explicit authorization to download, decrypt, store, and process it. The Actor does not log into private accounts or override entitlement checks.

### Legal use and support

This Actor is intended only for authorized Hongguo media workflows. Copyrighted media and personal data may be protected by platform terms, copyright law, the GDPR, and other regulations. Do not process or redistribute content without a legitimate legal basis; consult qualified counsel if you are unsure.

For help, open the **Issues** tab and include the run URL without posting credentials or signed media links. Use the **API** tab for programmatic integration examples.

# Actor input Schema

## `seriesIds` (type: `array`):

One or more unique numeric Hongguo short-drama series IDs. Every episode returned for each series is processed.

## Actor input object example

```json
{
  "seriesIds": [
    "7639686403294497854"
  ]
}
```

# Actor output Schema

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

Dataset containing per-episode status, media details, and KVS record links

## `files` (type: `string`):

Default Key-value store containing playable MP4 and metadata records

# 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 = {
    "seriesIds": [
        "7639686403294497854"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("spider_studio/hongguo-series-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 = { "seriesIds": ["7639686403294497854"] }

# Run the Actor and wait for it to finish
run = client.actor("spider_studio/hongguo-series-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 '{
  "seriesIds": [
    "7639686403294497854"
  ]
}' |
apify call spider_studio/hongguo-series-download-kvs --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,spider_studio/hongguo-series-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/cwcZGOO46XLNGV3o3/builds/3viqoViNAYUXAMEVw/openapi.json