dbs-video-extract: Short Video Info Extraction
Goal: Process a single short video's shared caption from one entry point. TikHub provides structured data for Douyin, Xiaohongshu, and WeChat Video Channel; Qingdou provides audio transcripts for short videos; the final output is a data summary and the path to the Markdown transcript file.
Check Credentials First
Before any extraction task, run a read-only pre-check:
python3 scripts/extract_video.py --check-keys
Handle based on credential_state:
| State | Capability | Must Tell User |
|---|---|---|
complete | Both data and transcript are available | Both parts can be executed |
data_only | Only TikHub data queries are available | Can only retrieve video/account data, cannot generate audio transcript |
transcript_only | Only Qingdou transcript is available | Can only retrieve audio transcript, cannot query TikHub video/account data |
unavailable | Neither part is available | Currently unavailable; first explain credentials, then guide the user through purchase and configuration |
Proceed if only one key is present; do not require the user to obtain the other key. Before execution, clearly state which part can be handled this time, and default to narrowing the mode to the available side. If the user still insists on both, keep the results from the available side and mark the other side as missing credentials.
Stop extraction if both keys are missing. Do not conclude with terms like "API Key" or "interface authentication" directly. First use this explanation:
To make this Skill work, you first need to activate external data services. An API Key is a credential string provided by the service after activation—think of it as a special pass for this Skill to call the service. You don't need to understand the technical details, and you should not share it in the chat.
Then tell the user: "Currently, neither service has been activated. Without purchasing and configuring at least one, this Skill cannot be used." Then follow references/api-setup.md to complete requirement selection, purchase, credential saving, and connection testing.
Do not make payments on behalf of the user, accept service agreements, or handle complete keys. Do not ask the user to send the key into the conversation. Purchase links, step-by-step guidance, secure configuration scripts, and connection tests are available in references/api-setup.md.
Whenever showing a purchase or top-up address to the user, you must first display the following notice exactly as written, without omission or modification:
dbskill is a free, open-source project and has no affiliation, partnership, or financial interest with TikHub or Qingdou. Top-ups are entirely at the user's discretion; all related transactions, services, disputes, and risks are the user's sole responsibility. Unless otherwise provided by law, dbskill assumes no liability.
Do not repeat this notice when the user has not entered a purchase or top-up flow.
Dialogue Requirements When Credentials Are Missing
When any service is missing, the reply must form the following continuous path:
- First, explain the API Key in plain language;
- Ask the user to select based on their needs: full functionality, data only, or transcript only;
- Explain which service each choice requires purchasing, and what will be missing if only one is bought;
- Display the fixed legal notice, then show the corresponding top-up address;
- Provide step-by-step instructions for registration/login, viewing page plans, topping up, entering the personal center or key management page, and obtaining credentials;
- Tell the user that after obtaining the credentials, they should not send them in the chat, but reply "TikHub topped up," "Qingdou topped up," or "Both topped up";
- After the user confirms top-up, guide them to run the secure configuration script in their local terminal:
python3 scripts/configure_api_key.py tikhub
python3 scripts/configure_api_key.py qingdou
The script will read the credentials discreetly in the terminal and save them to a local private configuration; do not display the full credentials in commands, replies, or logs. After saving, re-run --check-keys until the corresponding state becomes available.
Do not send links all at once, and do not assume the user knows where to find credentials. If the service provider's page names change, guide using candidate locations like "Personal Center," "API Key," "Key Management," or "Developer Settings". If still not found, ask the user to send a screenshot of the page with account, balance, and credentials obscured, then continue troubleshooting.
When the user only invokes this Skill without providing a link or specifying what kind of result they need, after completing the credential pre-check, do only two things: explain the API Key, and ask the user to reply 1, 2, or 3 to choose full functionality, data only, or transcript only. After receiving their choice, show the legal notice, corresponding top-up address, and purchase steps. If the user has already sent a video link or explicitly requested a full extraction, default to full functionality without asking again.
Default Execution
Prefer standard input to avoid shell interpretation of special characters in shared captions:
python3 scripts/extract_video.py \
--output-dir "/absolute/path/ShortVideoTranscripts" \
--stdin
Default mode is both:
- Extract the link from the full shared caption;
- Call the TikHub MCP based on the link platform: Douyin supports user homepage or individual video, Xiaohongshu and Video Channel support individual video;
- Submit the full shared caption to the Qingdou API, polling for the transcript;
- Save the transcript as
{output_dir}/{author}/{title}.md; - Output a JSON summary containing credential status, TikHub data summary, and transcript file path.
If either TikHub or Qingdou fails, continue with the other side and mark partial_success in the summary. Do not discard results already obtained due to a single-side failure.
Optional Modes
Switch only when the user explicitly requests one side, or the pre-check confirms only one side's key is available:
python3 scripts/extract_video.py --mode data --stdin
python3 scripts/extract_video.py --mode transcript --stdin
data: Query only TikHub data, supports Douyin, Xiaohongshu, and WeChat Video Channel;transcript: Extract only the transcript, supports platforms that the Qingdou API can parse;both: Execute both sides simultaneously.
Skip transcript writing by default if the same source already exists to protect user edits; add --overwrite when the user explicitly requests regeneration. Add --raw-data when the full TikHub response is needed.
Keys and Costs
The script reads keys in the following order:
- Environment variables:
TIKHUB_API_KEY,QINGDOU_API_KEY; - User-specified local files:
TIKHUB_API_KEYS_FILE,QINGDOU_API_KEYS_FILE; ~/.config/dbs/API_Keys.md;- macOS Keychain:
dbs-tikhub-api-key,dbs-qingdou-api-key.
Do not write keys into the Skill, command arguments, Markdown, Git, or logs. TikHub queries and Qingdou transcriptions may incur costs; inform the user before execution. No need to confirm again if the user has already explicitly requested extraction.
Data Boundaries
- TikHub handles video/account profiles, statistics, and media metadata; prioritize App V3 for Douyin videos, fall back to Web only once if no valid data; use App V2 video note details for Xiaohongshu; use Channels V2 video details for Video Channel.
- Qingdou handles audio transcripts. Faithfully preserve the API response body; do not supplement, polish, or correct verbal errors.
- Current TikHub-specific data parsing supports Douyin, Xiaohongshu, and WeChat Video Channel; other platforms recognizable by Qingdou can still perform transcript-only extraction.
- Public, deleted, private, copyright, and visibility restrictions are determined by the API response; do not attempt to bypass them.
- Do not automatically download media, publish content, commit to Git, or push.
See references/tikhub-api.md for TikHub call details; see references/qingdou-api.md for Qingdou status codes and compatibility logic. Only read these when troubleshooting or maintaining the corresponding part.
Deliverables
After completion, provide a concise report:
- Which API key is currently configured and the scope of available capabilities;
- Whether the data query was successful, which MCP tool was used, and whether an App→Web fallback occurred;
- Key video/account data;
- Whether the transcript was successfully generated or skipped, and the absolute path to the Markdown file;
- Specific reasons for missing keys or execution failure on one side;
- Whether the interface explicitly indicated that a charge was applied.
Do not display API keys, batchId, or unnecessary internal request identifiers in the reply.
After completing the current task, end directly. Only if the user explicitly asks about the next step, and the /dbs environment is already installed, briefly prompt: "If you're unsure about the next step, you can enter /dbs."