RedNote (Xiaohongshu) Video Downloader API

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

Submit the complete public video-note URL with its matching xsec_token. This keeps resolution on the direct RedNote path for lower-cost video extraction.

Process 1–1,000 complete Xiaohongshu video-note URLs and receive one structured Dataset record per submitted item, with a playback-friendly bestVideoUrl, all detected stream variants, and structured note, creator, and engagement metadata.

• Direct video URLs for download and downstream storage workflows
• bestVideoUrl plus all detected stream variants in one result
• H.264-first best-video selection for broad playback compatibility
• Structured note, creator, engagement, and media metadata included
• Batch processing up to 1,000 inputs with duplicate-aware billing
• 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.

Multiple qualities included

Every successful result includes bestVideoUrl and all detected stream variants, so you can choose codec, resolution, or quality. Multiple returned qualities do not create additional video-result charges.

Flexible RedNote/Xiaohongshu inputs

Use complete supported Xiaohongshu video-note URLs containing their matching token.

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. Use the included metadata and alternate qualities as needed.

The smallest valid input is:

{
  "urls": ["https://www.xiaohongshu.com/explore/6a673660000000002201bdf0?xsec_token=ABpmxG_iiqv6i0PvH66YtPs66TX1rjAfCHs8s4EGoqXdk=&xsec_source=pc_search&source=web_explore_feed"]
}

Supported RedNote / Xiaohongshu inputs

The Actor accepts complete HTTP or HTTPS Xiaohongshu video-note URLs in these forms:

• https://www.xiaohongshu.com/explore/{noteId}?xsec_token=...
• https://www.xiaohongshu.com/discovery/item/{noteId}?xsec_token=...
• https://www.xiaohongshu.com/red_video/{noteId}?xsec_token=...

The note ID is the 24-character hexadecimal value after /explore/, /discovery/item/, or /red_video/ in the complete URL.

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.

Supported paths are normalized to a canonical explore URL. Duplicate detection uses the canonical note ID.

Note ID and required xsec_token

A valid xsec_token is required and must remain in the same URL as its video note. Open the public note from Xiaohongshu search, feed, or sharing, then copy the complete browser URL; the token appears after ? or &. Keeping it in the URL improves direct-resolution reliability.

There is no separate run-level token input. Missing, expired, invalid, or mismatched tokens can cause validation or resolution failure and do not provide access to private content or bypass permissions.

Request URLs are sanitized before logging. The Dataset input field preserves the submitted URL, while normalizedUrl omits query parameters.

Input

Field	Type	Required	Default	Limits	Description
urls	string[]	Yes	None	1–1,000 items	Complete supported video-note URLs containing a valid matching xsec_token. Items are normalized and deduplicated by canonical note identity.

Every successful result includes structured note metadata, the best video URL, and all detected qualities.

Input examples

Single video

{
  "urls": ["https://www.xiaohongshu.com/explore/6a673660000000002201bdf0?xsec_token=ABpmxG_iiqv6i0PvH66YtPs66TX1rjAfCHs8s4EGoqXdk=&xsec_source=pc_search&source=web_explore_feed"]
}

Batch input

{
  "urls": [
    "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4?xsec_token=TOKEN_FOR_FIRST_NOTE",
    "https://www.xiaohongshu.com/red_video/6a84418900000000270212b1?xsec_token=TOKEN_FOR_SECOND_NOTE",
    "https://www.xiaohongshu.com/explore/6a840ef900000000270231e6?xsec_token=TOKEN_FOR_THIRD_NOTE"
  ]
}

Short output example

{
  "input": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4?xsec_token=...",
  "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, structured note metadata, and media.variants.

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 when available.
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[]	Successful video	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.

Note metadata

These fields are included in successful video records.

Field	Type	Availability	Meaning
title	string	Successful video	Native note title. It can be an empty string; share text is not used as a fallback title.
description	string	Successful video	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[]	Successful video	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	Successful video	Xiaohongshu user ID; can be empty if unavailable.
author.nickname	string	Successful video	Display name.
author.avatarUrl	string	When available	Direct avatar URL.
author.profileUrl	string | null	Successful video	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	Successful video	Normalized like count.
engagement.comments	number	Successful video	Normalized comment count.
engagement.collects	number	Successful video	Normalized collection/save count.
engagement.shares	number	Successful video	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
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 was found.
XSEC_TOKEN_REQUIRED	invalid_input	The full video-note URL did not include the required token.
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.
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

{
  "input": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4?xsec_token=...",
  "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

{
  "input": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4?xsec_token=...",
  "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

{
  "input": "https://www.xiaohongshu.com/red_video/6a87dbad0000000005030ca4?xsec_token=...",
  "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": "https://www.xiaohongshu.com/explore/6a87dbad0000000005030ca4?xsec_token=...",
  "scrapedAt": "2026-08-22T02:00:00.000Z"
}

Image-only note

{
  "input": "https://www.xiaohongshu.com/explore/6a840ef900000000270231e6?xsec_token=...",
  "success": false,
  "status": "unsupported_note_type",
  "error": {
    "code": "NOT_A_VIDEO_NOTE",
    "message": "This RedNote post does not contain a downloadable video."
  }
}

Invalid input

{
  "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

{
  "input": "https://www.xiaohongshu.com/explore/6a67603c000000000503be3f?xsec_token=...",
  "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/xiaohongshu-video-downloader-api.

JavaScript

import { ApifyClient } from 'apify-client';

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

const run = await client.actor('lance_api/xiaohongshu-video-downloader-api').call({
  urls: ['https://www.xiaohongshu.com/explore/6a673660000000002201bdf0?xsec_token=ABpmxG_iiqv6i0PvH66YtPs66TX1rjAfCHs8s4EGoqXdk=&xsec_source=pc_search&source=web_explore_feed'],
});

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

Python

import os
from apify_client import ApifyClient

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

run = client.actor("lance_api/xiaohongshu-video-downloader-api").call(run_input={
    "urls": ["https://www.xiaohongshu.com/explore/6a673660000000002201bdf0?xsec_token=ABpmxG_iiqv6i0PvH66YtPs66TX1rjAfCHs8s4EGoqXdk=&xsec_source=pc_search&source=web_explore_feed"],
})

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:

curl -X POST \
  "https://api.apify.com/v2/acts/lance_api~xiaohongshu-video-downloader-api/run-sync-get-dataset-items?format=json" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://www.xiaohongshu.com/explore/6a673660000000002201bdf0?xsec_token=ABpmxG_iiqv6i0PvH66YtPs66TX1rjAfCHs8s4EGoqXdk=&xsec_source=pc_search&source=web_explore_feed"]
  }'

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 price: $0.006 per successful video result — $6 per 1,000
• Lowest eligible discounted price: from $0.003 per successful video result — $3 per 1,000

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

One successful video costs the same whether one or multiple qualities are returned. A canonical successful video emits one video-result, regardless of the number of available stream variants.

Invalid inputs, unsupported URLs, missing/invalid tokens, deleted or inaccessible notes, image-only notes, missing video media, parse/fetch failures, 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. Validate the complete video-note URL and its required token.
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 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/xiaohongshu-video-downloader-api to resolve download-ready video URLs from these public RedNote/Xiaohongshu video-note URLs. Return the input, note ID, title, best video URL, available qualities, author, engagement, and processing status.

FAQ

Which RedNote/Xiaohongshu URLs are supported?

Supported note paths are /explore/{id}, /discovery/item/{id}, and /red_video/{id}. Submit the complete URL containing its matching token.

Can I submit note IDs directly?

No. This lower-cost Actor requires the complete public video-note URL containing its matching token.

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. Every successful result includes media.variants together with media.bestVideoUrl.

Does returning multiple qualities cost more?

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

What data does the Xiaohongshu Video Downloader return?

A successful result includes a direct bestVideoUrl, detected stream variants, video duration, cover URL, note title and description, author information, engagement counts, tags, timestamps, and processing metadata when available.

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?

Yes. Each submitted video-note URL must contain its valid matching token.

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/xiaohongshu-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
• 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
• 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, open an issue on the Actor page or email lanceapi2026@hotmail.com.

Include:

• Apify Run ID
• The affected public note URL
• Returned status and error.code
• Expected result and actual result

When posting publicly on the Issues page, you may redact the xsec_token value from the example URL.

Do not send Apify tokens, cookies, session credentials, API keys, passwords, or other private credentials.