Open API - Media Parsing Documentation

01 · Quickstart

Send a parsing request

Add your API key to the request header and submit one public media URL in the JSON body.

curl -X POST https://api.videotool.cc/openapi/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://..."}'

02 · Authentication

Authenticate with an API key

Send X-API-Key with each request. View or rotate the key in the API console.

X-API-KeyYOUR_API_KEY

Keep API keys on your server. Never place one in browser JavaScript, a mobile binary, or a public repository.

03 · Endpoint

Available endpoint

POST/openapi/parseSingle URL

Parse one public media URL

Submit one public post or video URL. One credit is charged after usable resources are returned.

url string · required Public post or video URL

04 · Response

Successful response

A successful call returns ParseResult in the standard AjaxResult wrapper, grouped into video, image, audio, and text resources.

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "resultCode": 0,
    "hasResource": true,
    "resourceType": 200,
    "descList": ["..."],
    "imgList": [],
    "videoList": [],
    "audioList": []
  }
}

Response fields

Fields can be empty depending on the source platform and resource type. Check code, data.resultCode, and data.hasResource before reading a resource list.

`code`	number	Business status code; 200 means the request succeeded.
`msg`	string	Processing message; failures include a displayable reason.
`data.resultCode`	number	Parse result code; 0 means parsing succeeded.
`data.resultMsg`	string \| null	Parse result message; normally null on success.
`data.hasResource`	boolean	Whether usable media was returned; one credit is charged only when true.
`data.resourceType`	number	Resource type returned by the parser; use the resource lists to identify actual content.
`data.parseBy`	number \| null	Parser source or strategy identifier for display and diagnostics only.
`data.ffmpegCmd`	string \| null	FFmpeg command template for source-required transcoding; normal browser playback does not run it.
`data.headers`	object	Headers that can be required for direct raw-media requests; normally unnecessary with webProxyUrl.
`data.canWatchAd`	boolean	Whether ad-based parse entitlement is supported; Open API clients normally do not use it.
`data.showProxy / data.proxyBaseUrl`	boolean / string \| null	Ordinary download-proxy settings, separate from the Web display proxy.
`data.timestamp`	number	Millisecond timestamp for this response; required in a web proxy URL.
`data.webProxyUrl`	string \| null	Web display proxy base URL; append /res/dl when present, otherwise use the resource URL.
`data.packageDownloadUrl`	string \| null	Package-download base URL, used only for /res/zip and generated /static paths.
`data.vipProxyBaseUrl / data.vipDownloadStatus`	string \| null	VIP fast-download fields; standard Open API integrations should not depend on them.
`data.vipPackageDownloadUrl / data.vipPackageDownloadStatus`	string \| null	VIP package-download fields; standard Open API integrations should not depend on them.
`data.descList[]`	string[] \| null	Original caption, title, or supplemental descriptions.
`data.author`	string \| null	Xiaohongshu author nickname when available.
`data.publishTime`	string \| null	Xiaohongshu publish time in yyyy-MM-dd HH:mm:ss format.
`data.publishTimestamp`	number \| null	Xiaohongshu publish timestamp in seconds.
`data.imgList[].url / origUrl`	string	Image resource URL and optional original source URL.
`data.imgList[].webImgHash`	string \| null	Web image proxy signature; fall back to imgHash only when it is absent.
`data.imgList[].videoUrl`	string \| null	Video linked to an image item when available.
`data.imgList[].webVideoHash`	string \| null	Web proxy signature for an image item linked video.
`data.videoList[].id`	string \| null	Video resource identifier for rendering or deduplication.
`data.videoList[].url / origUrl`	string	Video resource URL and optional original source URL.
`data.videoList[].width / height`	string \| null	Video dimensions in px when supplied by the source.
`data.videoList[].webVideoHash`	string \| null	Web video proxy signature; fall back to videoHash only when absent.
`data.videoList[].audioUrl`	string \| null	Separate audio resource URL when available.
`data.videoList[].webAudioHash`	string \| null	Web audio proxy signature; fall back to audioHash only when absent.
`data.videoList[].desc`	string \| null	Supplemental description for the video resource.
`data.audioList[].url / origUrl`	string	Standalone audio URL and optional original source URL.

05 · Proxy URLs

Use the web display proxy URL

When webProxyUrl is present, browsers can use a proxied resource URL to handle CORS or origin hotlink restrictions. Use the raw resource URL when it is empty.

const data = result.data;
const video = data.videoList[0];
const rawUrl = video.url;

const displayUrl = data.webProxyUrl
  ? data.webProxyUrl.replace(/\/+$/, '')
    + '/res/dl?url=' + encodeURIComponent(rawUrl)
    + '&hash=' + (video.webVideoHash || video.videoHash)
    + '&timestamp=' + data.timestamp
  : rawUrl;

// <video src={displayUrl} controls />

Signature and resource rules

Use webImgHash (falling back to imgHash) for images, webVideoHash (falling back to videoHash) for videos, and webAudioHash (falling back to audioHash) for video audio. Use only the hash and timestamp returned by the same parse response. Do not use webProxyUrl for /res/zip package downloads.

06 · Errors

Business error codes

code	Meaning	Charge
`400`	Missing or invalid URL	Not charged
`401`	Missing, invalid, or disabled API key	Not charged
`403`	Insufficient credits	Not charged
`422`	No usable resource was returned	Not charged
`500`	Parsing service error	Not charged

07 · Billing

Charge successful results only

1credit charged when usable resources are returned

0credits charged for failures, errors, or empty results

Current scope

The Open API exposes only POST /openapi/parse for one URL. Batch, capabilities, idempotency cache, and rate-limit endpoints are not provided.

Add media parsing with one endpoint