# Xiaohongshu (RedNote) Video Downloader API – No xsec\_token (`lance_api/rednote-video-downloader-api`) Actor

Get downloadable video URLs from public Xiaohongshu (RedNote) video notes without requiring xsec\_token. Submit note IDs, URLs, short links, or share text and receive structured video data for automation.

- **URL**: https://apify.com/lance\_api/rednote-video-downloader-api.md
- **Developed by:** [LanceAPI](https://apify.com/lance_api) (community)
- **Categories:** Social media, Developer tools, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $30.00 / 1,000 video results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## RedNote (Xiaohongshu) Video Downloader API – No xsec\_token Required

**Turn public RedNote/Xiaohongshu video notes into direct, download-ready video URLs with optional metadata and multiple available qualities—without storing large MP4 files in your Apify storage.**

**No `xsec_token` is required for normal use. If you already have a valid token in the URL or provide one separately, the Actor can use it when resolving that public note.**

Submit a 24-character note ID, full Xiaohongshu URL, supported XHS short link, or app share text. Process 1–1,000 inputs and receive one structured Dataset record per submitted item, with a playback-friendly `bestVideoUrl`, optional stream variants, and optional note metadata.

- Direct video URLs for download and downstream storage workflows
- H.264-first best-video selection for broad playback compatibility
- Optional metadata and alternate-quality output
- Batch processing with isolated failures
- Duplicate-aware resolution: one record per input, one charge per canonical success
- **No valid video URL, no `video-result` charge**

### ✨ Key features

#### Direct download-ready video URLs

Receive `media.bestVideoUrl` without first saving the MP4 file in Apify storage. Pass the URL to your downloader, backend, automation, or authorized storage workflow.

#### Playback-friendly best video selection

When multiple streams are available, the Actor prioritizes codecs in this order: H.264, H.265, AV1, then unknown codecs. Within the same codec, it prefers higher resolution, bitrate, and file size when those values are available.

#### Optional multiple qualities

Keep only `bestVideoUrl` for a smaller response, or include every detected stream variant when you need a choice of codec, resolution, or quality. Multiple returned qualities do not create additional `video-result` charges.

#### Flexible RedNote/Xiaohongshu inputs

Use bare note IDs, supported full URLs, `xhslink.com` or `xhslink.cn` short links, Markdown-wrapped links, and complete app share text.

#### Batch up to 1,000 inputs

Process large lists with bounded concurrency. An invalid, deleted, inaccessible, image-only, or unparseable item does not stop the remaining inputs.

#### Duplicate-aware processing

Every submitted input receives its own Dataset record. Equivalent notes are resolved and charged only once; later records are marked with `duplicate` and `duplicateOf`.

### 🚀 Quick start

Use the Actor in Apify Console:

1. Add one RedNote/Xiaohongshu video note to `urls`.
2. Click **Start**.
3. Open the run's **Dataset**.
4. Read `media.bestVideoUrl`.
5. Turn metadata or alternate qualities off when you want a smaller response.

The smallest valid input is:

```json
{
  "urls": ["6a87dbad0000000005030ca4"]
}
```

### Supported RedNote / Xiaohongshu inputs

The Actor accepts:

- A 24-character hexadecimal note ID, such as `6a87dbad0000000005030ca4`
- `https://www.xiaohongshu.com/explore/{noteId}`
- `https://www.xiaohongshu.com/discovery/item/{noteId}`
- `https://www.xiaohongshu.com/red_video/{noteId}`
- HTTP or HTTPS short links from `xhslink.com` and `xhslink.cn`
- Complete app share text containing a supported link
- Markdown-wrapped supported links

A note ID is usually the cleanest input. You can find it in a supported note URL after `/explore/`, `/discovery/item/`, or `/red_video/`, or in the `noteId`/`id` field returned by another RedNote search or user-notes workflow.

Profile URLs, user pages, search pages, and unrelated Xiaohongshu pages are not supported. Image-only note URLs can be submitted, but they return `unsupported_note_type` because this Actor requires a downloadable video.

Short-link redirects, tracking parameters, and equivalent supported paths are normalized to a canonical explore URL. Duplicate detection uses the canonical note ID.

#### Note IDs and `xsec_token`

`xsec_token` is optional. Normally, submit a note ID or URL without one. If a public note URL already contains a valid token, the Actor can use it, or you can provide the token through the separate `xsecToken` input.

If both are supplied, the separate `xsecToken` field takes precedence over the URL token. It is a run-level value, so keep different note-specific tokens in their matching URLs when processing a batch. A missing token is allowed. An expired or mismatched token can cause resolution to fail and does not provide access to private content or bypass permissions.

The separate `xsecToken` field is not returned in Dataset records, and request URLs are sanitized before logging. However, `input` preserves the exact submitted value, so a token embedded directly in a submitted URL remains visible in that record's `input` field.

### Input

| Field | Type | Required | Default | Limits | Description |
|---|---|---:|---|---|---|
| `urls` | `string[]` | Yes | None | 1–1,000 items | Note IDs, supported full URLs, short links, Markdown links, or app share text. Items are normalized and deduplicated by canonical note identity. |
| `xsecToken` | `string` | No | Empty | One run-level value | Optional token for a public note. It overrides a token found in the URL and is best suited to a single-note run. For note-specific batch tokens, keep each token in its corresponding URL. |
| `includeMetadata` | `boolean` | No | `true` | — | Include title, description, timestamps, author, engagement, and tags. Turn off for a smaller video-focused response. |
| `includeAllQualities` | `boolean` | No | `true` | — | Include `media.variants` in addition to `media.bestVideoUrl`. Turning it off changes output size, not the number of result charges. |
| `webSession` | `string` | No | Empty | One run-level value | Optional Xiaohongshu session value for public content you are authorized to access. Most users do not need it. It does not automate login, expose private content, or bypass access controls. |

Need only the download URL? Set both output switches to `false` for a smaller, cleaner response.

Need codec or resolution choice? Keep `includeAllQualities` enabled.

### Input examples

#### Download URL only

```json
{
  "urls": ["6a87dbad0000000005030ca4"],
  "includeMetadata": false,
  "includeAllQualities": false
}
```

#### Video URL with metadata and all qualities

```json
{
  "urls": ["https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4"],
  "includeMetadata": true,
  "includeAllQualities": true
}
```

#### Batch input

```json
{
  "urls": [
    "6a87dbad0000000005030ca4",
    "https://www.xiaohongshu.com/red_video/6a84418900000000270212b1",
    "https://www.xiaohongshu.com/explore/6a840ef900000000270231e6"
  ],
  "includeMetadata": false,
  "includeAllQualities": false
}
```

#### Separate `xsecToken`

Replace `<matching xsec_token>` with an optional valid token that belongs to the public note you are processing.

```json
{
  "urls": ["6a87dbad0000000005030ca4"],
  "xsecToken": "<matching xsec_token>",
  "includeAllQualities": false
}
```

### Short output example

```json
{
  "input": "6a87dbad0000000005030ca4",
  "normalizedUrl": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4",
  "success": true,
  "status": "success",
  "noteId": "6a87dbad0000000005030ca4",
  "noteType": "video",
  "coverUrl": "https://sns-webpic.example/cover.webp",
  "media": {
    "durationSeconds": 32.4,
    "bestVideoUrl": "https://sns-video.example/video.mp4"
  },
  "scrapedAt": "2026-08-22T02:00:00.000Z"
}
```

### Output

Results are written to the default Dataset in the same order as the submitted inputs. Every input receives one record, including failures and duplicates.

Successful video records always contain `media.bestVideoUrl`. Metadata fields are included only when `includeMetadata` is enabled. `media.variants` is included only when `includeAllQualities` is enabled.

Image-only notes and notes without an accessible video stream return failure records. They do not return `bestVideoUrl` and do not trigger `video-result` charges.

### Complete output field reference

#### Core result

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `input` | `string` | Always | Exact submitted input value. |
| `normalizedUrl` | `string` | Successful video | Canonical `https://www.xiaohongshu.com/explore/{noteId}` URL without tracking parameters. |
| `success` | `boolean` | Always | `true` only when a valid downloadable video URL was returned. |
| `status` | `string` | Always | Stable processing outcome. See **Status values**. |
| `noteId` | `string` | Successful video | Canonical RedNote/Xiaohongshu note ID. |
| `noteType` | `string` | Successful video | `video`. Non-video notes return a failure record instead. |
| `scrapedAt` | `string` | Successful video | UTC ISO 8601 timestamp for result creation. |

#### Video and media

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `coverUrl` | `string` | When available | Direct cover-image URL. This remains available when metadata is disabled. |
| `media.durationSeconds` | `number` | Successful video | Video duration in seconds. May be `0` if the source provides no duration. |
| `media.bestVideoUrl` | `string` | Successful video | Selected direct video URL. The Actor requires this field before marking a result successful or charging it. |
| `media.variants` | `object[]` | When `includeAllQualities` is `true` | Detected stream variants in source order. May be an empty array. |
| `media.variants[].codec` | `string` | Per variant | `h264`, `h265`, `av1`, or `unknown`. |
| `media.variants[].url` | `string` | Per variant | Direct URL for that representation. |
| `media.variants[].width` | `number` | When available | Pixel width. |
| `media.variants[].height` | `number` | When available | Pixel height. |
| `media.variants[].duration` | `number` | When available | Variant duration in seconds. |
| `media.variants[].bitrate` | `number` | When available | Source-provided bitrate value. |
| `media.variants[].sizeBytes` | `number` | When available | Source-provided file size in bytes. |
| `media.variants[].qualityLabel` | `string` | When available | Source-provided quality label. |

The output does not invent MIME type, extension, or unavailable codec metadata.

#### Optional note metadata

These fields are omitted when `includeMetadata` is `false`.

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `title` | `string` | Metadata enabled | Native note title. It can be an empty string; share text is not used as a fallback title. |
| `description` | `string` | Metadata enabled | Native note description. |
| `createdAt` | `integer` | When available | Source creation time as a Unix timestamp in milliseconds. |
| `createdAtIso` | `string` | When valid | `createdAt` converted to UTC ISO 8601. |
| `updatedAt` | `integer` | When available | Source update time as a Unix timestamp in milliseconds. |
| `updatedAtIso` | `string` | When valid | `updatedAt` converted to UTC ISO 8601. |
| `tags` | `object[]` | Metadata enabled | Note topics/tags. Timestamp-style moment tags are excluded. |
| `tags[].id` | `string` | When available | Source tag ID. |
| `tags[].name` | `string` | Per tag | Tag name. |

#### Author

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `author.userId` | `string` | Metadata enabled | Xiaohongshu user ID; can be empty if unavailable. |
| `author.nickname` | `string` | Metadata enabled | Display name. |
| `author.avatarUrl` | `string` | When available | Direct avatar URL. |
| `author.profileUrl` | `string \| null` | Metadata enabled | Locally generated public profile URL, or `null` without a user ID. |
| `author.redId` | `string` | When available | Source-provided Red ID. |
| `author.verified` | `boolean` | When available | Source-provided verification flag. |

#### Engagement

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `engagement.likes` | `number` | Metadata enabled | Normalized like count. |
| `engagement.comments` | `number` | Metadata enabled | Normalized comment count. |
| `engagement.collects` | `number` | Metadata enabled | Normalized collection/save count. |
| `engagement.shares` | `number` | Metadata enabled | Normalized share count. |

#### Duplicate and error fields

| Field | Type | Availability | Meaning |
|---|---|---|---|
| `duplicate` | `boolean` | Duplicate inputs | `true` when the canonical note was already processed earlier in the same run. |
| `duplicateOf` | `string` | Duplicate inputs | Original input value of the first matching record. |
| `error.code` | `string` | Failed results | Stable machine-readable failure code. |
| `error.message` | `string` | Failed results | Safe user-facing explanation. |

### Status values

`status` describes the overall result category. `error.code` gives the more specific failure reason.

| Status | Meaning | Video URL | Charged? |
|---|---|---:|---:|
| `success` | A valid video note and `bestVideoUrl` were returned. | Yes | One canonical `video-result` |
| `invalid_input` | Input was empty, malformed, or could not become a note URL. | No | No |
| `unsupported_url` | Domain, protocol, or Xiaohongshu path is unsupported. | No | No |
| `short_link_resolution_failed` | A supported short link could not be resolved. | No | No |
| `note_not_found` | The note was missing or no longer publicly accessible. | No | No |
| `access_denied` | The public note request was denied. | No | No |
| `page_fetch_failed` | Note data could not be retrieved after retries. | No | No |
| `parse_failed` | Retrieved note data could not be parsed safely. | No | No |
| `unsupported_note_type` | The submitted note is image-only or otherwise not a video note. | No | No |
| `media_not_found` | A video note was found but no accessible video stream was returned. | No | No |
| `internal_error` | An unexpected per-input error occurred. | No | No |

A duplicate of a successful canonical record can also have `status: "success"`, but the duplicate record does not trigger another charge.

### Error codes

| Error code | Status | Meaning |
|---|---|---|
| `EMPTY_INPUT` | `invalid_input` | The item was empty. |
| `URL_NOT_FOUND` | `invalid_input` | No supported URL or note ID was found. |
| `INVALID_URL` | `invalid_input` | Extracted URL syntax was invalid. |
| `INPUT_REQUIRES_RESOLVABLE_URL` | `invalid_input` | Input could not be converted into a public note URL. |
| `UNSUPPORTED_PROTOCOL` | `unsupported_url` | Protocol is not HTTP or HTTPS. |
| `UNSUPPORTED_DOMAIN` | `unsupported_url` | Domain is not supported. |
| `UNSUPPORTED_PATH` | `unsupported_url` | URL is not a supported note page. |
| `SHORT_LINK_RESOLUTION_FAILED` | `short_link_resolution_failed` | Short-link redirect failed or returned an invalid destination. |
| `NOTE_NOT_FOUND` | `note_not_found` | Note was missing or unavailable. |
| `ACCESS_DENIED` | `access_denied` | Public note request was denied. |
| `PAGE_FETCH_FAILED` | `page_fetch_failed` | Public note page could not be fetched after retries. |
| `INITIAL_STATE_NOT_FOUND` | `parse_failed` | Expected public note state was missing. |
| `INITIAL_STATE_INVALID` | `parse_failed` | Public note state was incomplete or invalid. |
| `NOTE_DATA_INVALID` | `parse_failed` | Note data had an unexpected structure. |
| `NOT_A_VIDEO_NOTE` | `unsupported_note_type` | The note contains no downloadable video. |
| `VIDEO_MEDIA_NOT_FOUND` | `media_not_found` | No accessible video stream was found. |
| `INTERNAL_ERROR` | `internal_error` | Unexpected per-input processing error. |

### Output examples

#### Successful video note with all qualities

```json
{
  "input": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4",
  "normalizedUrl": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4",
  "success": true,
  "status": "success",
  "noteId": "6a87dbad0000000005030ca4",
  "noteType": "video",
  "coverUrl": "https://sns-webpic.example/cover.webp",
  "media": {
    "durationSeconds": 56,
    "bestVideoUrl": "https://sns-video.example/h264-1080.mp4",
    "variants": [
      {
        "codec": "h264",
        "url": "https://sns-video.example/h264-1080.mp4",
        "width": 1080,
        "height": 1920,
        "duration": 56,
        "bitrate": 2400000,
        "qualityLabel": "HD"
      },
      {
        "codec": "h265",
        "url": "https://sns-video.example/h265-2160.mp4",
        "width": 2160,
        "height": 3840
      }
    ]
  },
  "title": "Example video note",
  "description": "Example description",
  "createdAt": 1766571252000,
  "createdAtIso": "2025-12-24T10:14:12.000Z",
  "author": {
    "userId": "66ec990b000000001d031c8b",
    "nickname": "Example creator",
    "avatarUrl": "https://sns-avatar.example/avatar.webp",
    "profileUrl": "https://www.xiaohongshu.com/user/profile/66ec990b000000001d031c8b"
  },
  "engagement": {
    "likes": 1200,
    "comments": 18,
    "collects": 44,
    "shares": 9
  },
  "tags": [{ "id": "topic", "name": "Swimming" }],
  "scrapedAt": "2026-08-22T02:00:00.000Z"
}
```

#### Successful video note with only the best URL

```json
{
  "input": "6a87dbad0000000005030ca4",
  "normalizedUrl": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4",
  "success": true,
  "status": "success",
  "noteId": "6a87dbad0000000005030ca4",
  "noteType": "video",
  "coverUrl": "https://sns-webpic.example/cover.webp",
  "media": {
    "durationSeconds": 56,
    "bestVideoUrl": "https://sns-video.example/h264-1080.mp4"
  },
  "scrapedAt": "2026-08-22T02:00:00.000Z"
}
```

#### Duplicate input

```json
{
  "input": "https://www.xiaohongshu.com/red_video/6a87dbad0000000005030ca4",
  "normalizedUrl": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4",
  "success": true,
  "status": "success",
  "noteId": "6a87dbad0000000005030ca4",
  "noteType": "video",
  "media": {
    "durationSeconds": 56,
    "bestVideoUrl": "https://sns-video.example/h264-1080.mp4"
  },
  "duplicate": true,
  "duplicateOf": "6a87dbad0000000005030ca4",
  "scrapedAt": "2026-08-22T02:00:00.000Z"
}
```

#### Image-only note

```json
{
  "input": "6a840ef900000000270231e6",
  "success": false,
  "status": "unsupported_note_type",
  "error": {
    "code": "NOT_A_VIDEO_NOTE",
    "message": "This RedNote post does not contain a downloadable video."
  }
}
```

#### Invalid input

```json
{
  "input": "https://www.xiaohongshu.com/user/profile/example",
  "success": false,
  "status": "unsupported_url",
  "error": {
    "code": "UNSUPPORTED_PATH",
    "message": "This Xiaohongshu URL is not a supported note page."
  }
}
```

#### Deleted or inaccessible note

```json
{
  "input": "6a67603c000000000503be3f",
  "success": false,
  "status": "note_not_found",
  "error": {
    "code": "NOTE_NOT_FOUND",
    "message": "The RedNote note could not be found or is no longer publicly accessible."
  }
}
```

### API usage

The Actor slug is `lance_api/rednote-video-downloader-api`.

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('lance_api/rednote-video-downloader-api').call({
  urls: ['6a87dbad0000000005030ca4'],
  includeMetadata: true,
  includeAllQualities: false,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]?.media?.bestVideoUrl);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("lance_api/rednote-video-downloader-api").call(run_input={
    "urls": ["6a87dbad0000000005030ca4"],
    "includeMetadata": True,
    "includeAllQualities": False,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items[0].get("media", {}).get("bestVideoUrl"))
```

#### cURL

This synchronous endpoint runs the Actor and returns the default Dataset items:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/lance_api~rednote-video-downloader-api/run-sync-get-dataset-items?format=json" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["6a87dbad0000000005030ca4"],
    "includeMetadata": false,
    "includeAllQualities": false
  }'
```

In the returned JSON array, read `[0].media.bestVideoUrl`.

### 💰 Simple, transparent pricing

You pay only for canonical results that successfully return a valid `media.bestVideoUrl`.

- **Standard Free price:** $0.040 per successful video result — **$40 per 1,000**
- **Lowest eligible discounted price:** from $0.030 per successful video result — **$30 per 1,000**

Check the Actor's **Pricing** tab for the current rate available to your Apify plan.

One successful canonical video emits one `video-result`. Returning multiple available qualities still emits only one event.

Invalid inputs, unsupported URLs, failed short links, deleted or inaccessible notes, image-only notes, missing video media, parse/fetch failures, invalid or expired token failures, unsuccessful session-assisted requests, and duplicate-only records do not add a `video-result` charge.

**No valid video URL, no `video-result` charge.**

### Use cases

- **Video download automation:** Pass temporary download-ready URLs to your own downloader or storage workflow.
- **Media catalogs:** Build structured catalogs with video URLs, covers, note metadata, authors, and engagement.
- **Creator and competitor research:** Analyze public video-note metadata that you are authorized to collect.
- **Content research:** Combine video URLs and structured context in downstream datasets.
- **Backup and archival workflows:** Copy permitted media to your storage before temporary CDN URLs expire.
- **AI and RAG workflows:** Use public note text and metadata as context for downstream language-model systems.
- **API automation:** Connect a Xiaohongshu Video Downloader to n8n, Make, Zapier, backend jobs, or data pipelines.

### How it works

1. Parse the note ID, full URL, short link, Markdown link, or share text.
2. Normalize it to a canonical RedNote/Xiaohongshu note identity.
3. Deduplicate equivalent inputs while preserving one record per submitted item.
4. Resolve the public video note and its available streams.
5. Select the best compatible video and optionally include all detected variants.
6. Save normalized success or failure records to the default Dataset in input order.

### 🤖 Use with AI agents

Use this Actor through the Apify MCP Server from ChatGPT, Claude, Cursor, Codex, or another MCP-compatible client. MCP runs use the same Actor pricing as normal Apify runs.

Example prompt:

> Use the Apify Actor `lance_api/rednote-video-downloader-api` to resolve download-ready video URLs from these public RedNote/Xiaohongshu video notes. Return the input, note ID, title, best video URL, available qualities, author, engagement, and processing status. Prefer only the best compatible video unless I explicitly ask for all qualities.

### FAQ

#### Which RedNote/Xiaohongshu URLs are supported?

Supported note paths are `/explore/{id}`, `/discovery/item/{id}`, and `/red_video/{id}`. The Actor also accepts `xhslink.com`/`xhslink.cn` short links and app share text containing a supported link.

#### Can I submit note IDs directly?

Yes. A 24-character hexadecimal note ID is the preferred input.

#### Can I process up to 1,000 notes?

Yes. `urls` accepts 1–1,000 items, and each submitted item receives one Dataset record.

#### Does the Actor download MP4 files into Apify storage?

No. It returns direct media URLs. Download or copy permitted media separately if you need permanent storage.

#### What is `bestVideoUrl`?

It is the direct video URL selected for broad playback compatibility and then quality within the selected codec.

#### How does the Actor choose the best video?

It prefers H.264, then H.265, AV1, and unknown codecs. Within one codec, it prefers higher resolution, bitrate, and size when available.

#### Can I get multiple video qualities?

Yes. Keep `includeAllQualities: true` to receive `media.variants`. Set it to `false` to keep only `bestVideoUrl`.

#### Does returning multiple qualities cost more?

No. A canonical successful note is charged once even when multiple qualities are returned.

#### Are duplicate inputs charged twice?

No. Canonical duplicates keep individual Dataset records but are resolved and charged only once per run.

#### What happens if I submit an image-only note?

It returns `success: false`, `status: "unsupported_note_type"`, and `error.code: "NOT_A_VIDEO_NOTE"`. It has no `bestVideoUrl` and no `video-result` charge. Metadata is not returned for this failure record.

#### Are video URLs permanent?

No. They are RedNote/Xiaohongshu CDN URLs returned at processing time, and some include temporary signatures. Download or copy permitted media to your own storage promptly when you need long-term access.

#### Do I need `xsec_token`?

Usually not. Provide a valid matching token only when you already have one for a public note that requires it. The separate field overrides a token in the URL.

#### Do I need `webSession`?

Usually not. Use it only for direct public-page requests with a session you are authorized to use. It does not automate login, expose private content, or bypass permissions.

#### Can this Actor access private content?

No. It is designed for publicly accessible notes and does not bypass login or access controls.

#### How am I charged?

Only a canonical successful result with a valid `media.bestVideoUrl` emits one `video-result`. Failures and duplicate-only records do not add that charge.

#### Can an AI agent use this Actor?

Yes. Use `lance_api/rednote-video-downloader-api` through the Apify API or Apify MCP Server.

### Limitations

- Publicly accessible content only; no login automation or access-control bypass
- Image-only notes do not produce video URLs
- Deleted, unavailable, or restricted notes can fail
- Profile, user, and search pages are unsupported
- Short-link handling depends on a valid redirect response
- `xsec_token` values can expire or become invalid
- Returned CDN media URLs can expire or stop working
- Available codec, resolution, bitrate, and quality fields vary by note
- Optional metadata fields can be empty, null, or omitted when unavailable
- Platform changes can temporarily affect resolution or parsing
- The Actor does not permanently host or store video files

### Public data and responsible use

Use this Actor only for lawful access to public content. Respect RedNote/Xiaohongshu terms, Apify terms, copyright, privacy, and applicable law. Do not use it for harassment, spam, unlawful profiling, attempts to access private information, or access-control bypass.

### Support

For help, contact **lanceapi2026@hotmail.com** and include:

- Apify Run ID
- A non-sensitive note ID or public URL
- Returned `status` and `error.code`
- Expected result and actual result

Do not send Apify tokens, cookies, `webSession` values, `xsec_token` values, API keys, or passwords.

# Actor input Schema

## `urls` (type: `array`):

Add 1–1000 notes. A 24-character hexadecimal note ID is preferred. Find it after /explore/, /discovery/item/, or /red\_video/ in a Xiaohongshu URL, or in the noteId/id field of a search or user-notes result. Full xiaohongshu.com links, xhslink.com/xhslink.cn short links, and complete app share text are also supported.

## `xsecToken` (type: `string`):

No xsec\_token is required for normal use. If provided, this run-level value must match the public note and overrides a token already present in the URL. For batches with different note-specific tokens, keep each token in its corresponding URL. An expired or mismatched token can cause resolution to fail and does not provide access to private content or bypass permissions.

## `includeMetadata` (type: `boolean`):

Keep this on for title, author, engagement, and tags. Turn it off when you only need media URLs and want a smaller response.

## `includeAllQualities` (type: `boolean`):

Return every detected H.264, H.265, and AV1 stream in addition to the most compatible best video URL.

## `webSession` (type: `string`):

Optional session value you are authorized to use when a public note does not load normally. Most users should leave this empty.

## Actor input object example

```json
{
  "urls": [
    "6428b7be000000001300d335"
  ],
  "includeMetadata": true,
  "includeAllQualities": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (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 = {
    "urls": [
        "6428b7be000000001300d335"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("lance_api/rednote-video-downloader-api").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 = { "urls": ["6428b7be000000001300d335"] }

# Run the Actor and wait for it to finish
run = client.actor("lance_api/rednote-video-downloader-api").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 '{
  "urls": [
    "6428b7be000000001300d335"
  ]
}' |
apify call lance_api/rednote-video-downloader-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lance_api/rednote-video-downloader-api"
        }
    }
}

```

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/V3lBIxKFdO2GPYdPe/builds/SHYSp1FfaBeeufvbm/openapi.json