byted-kickart-viral-replicator

Viral Fission SKILL

🚨 Mandatory Pre-check Process

All KickArt operations must first complete the CLI availability and OAuth login status checks:

1. KickArt CLI Check
   • Read references/CLI前置校验指南.md。
   • Use command -v npm to check whether npm exec is available. All commands are invoked through npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli at a fixed version, with no global or project-level installation required.
   • Execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli auth_token >/dev/null to check login status; displaying, logging, or persisting the token is prohibited.
   • When not yet logged in or credentials have expired, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli auth_login to obtain the authorization link and display it to the user; this command returns immediately and does not poll the authorization status.
   • After waiting for the user to explicitly confirm that web authorization is complete, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli auth_complete once to obtain the token and complete login, then check the login status again; automatic polling or execution before user confirmation is prohibited.
   • If npm exec fails to download the package or the CLI is still unavailable, report the sanitized npm error and terminate the operation.
   • Do not require users to provide long-term keys, do not read or echo OAuth tokens, and do not directly request the OpenAPI.

🎯 Intent Recognition and Task Execution Guide (automatically identified based on conversation history)

After determining intent based on the current user input and history records,you must strictly read and follow the corresponding execution basis guide, and must not guess the execution steps out of thin air.

Task Type	Trigger Intent and Keywords	Execution Basis (Mandatory First Read)	Output Requirements	Prerequisites
Progress Query	【Highest Priority】When the user mentions "query progress", "view results", "how is the generation going", "is it done", or queries the status of a specific task ID.	Read references/任务查询指南.md, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli query_task_v2 --task-id <ID> --source ad_variations --auto-publish true。	Parse the stdout JSON and output the current status or result.	The corresponding task ID must be obtained from the session context; if there is no valid ID, directly inform the user that no related task was found.
Independent Material Ingestion	When the user explicitly requests "upload to KickArt", "create media asset", "save to material library", or "query media asset", and is not providing input materials for a generation task	Read references/素材上传指南.md, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli material_pipeline_v2 --file-path <绝对路径>	Output from the stdout JSON created.media_id and origin_url	Images and videos in generation tasks must not trigger this process; local materials are automatically uploaded by the submission command
Viral Fission	When the user mentions "viral fission", "viral clone", "copy video", "clone video", "same-style video", "generate same-style", "fission video", etc., or expresses equivalent intent to create content the same as a trending video.	Read references/爆款裂变指南.md, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli submit_viral_task_v2	Parse the stdout JSON and output the task ID; subsequently obtain the result through query_task_v2 to obtain the result	Reference videos, product information, and language must be collected step by step strictly according to Guide Phase 0; optional parameters such as character images, scene images, creative prompts, subtitles, subtitle erasure, and visible watermarks must also be asked about one by one. After completing information collection, the final video information must be displayed, and secondary confirmation and compliance prompts must be provided. Submission is strictly prohibited before confirmation.
Video reference	When the user proactively provides a reference video, a video link, or indicates that they want to upload a video	Read references/视频参考指南.md, validate and record the local absolute path or public URL; do not upload in advance	Obtain material values that can be passed directly to submit_viral_task_v2 --ref-video material value	The primary prerequisite step when the user triggers viral fission intent
Digital avatar	When the user mentions "add model," "custom character," "model on camera," "digital human," or "custom model"	Read references/数字形象指南.md, validate and record the local absolute path or public URL; do not upload in advance	Obtain the image list that can be passed directly to submit_viral_task_v2 --model-images image list	Triggered when the user needs to specify a character on camera in a fission task

⚠️ Error handling specification

All errors must clearly state the reason and an actionable solution; vague prompts are prohibited!!!

General error codes

Error code	Error type	Error description	Detailed explanation	Suggested user action
0	Success	Task successful	Task processing completed, result has been generated	-
1000	AsyncTaskRunning	Task running	Task is being processed, please poll for the result later	-
1300	AuthFailed	OAuth authentication failed	Login credentials are invalid or expired	Execute in sequence auth_login to obtain the authorization link, wait for the user to complete web authorization, and execute auth_complete to complete login; automatic retry of paid submission is prohibited, and the final video information must be displayed again and secondary confirmation obtained before resubmission
1400	ParamErr	Parameter error	The request contains invalid or missing parameters	Please check the request body structure, field types, and required fields against the documentation
1401	ConcurrentErr	Concurrency limit exceeded	The current number of concurrent requests exceeds the agreed limit	Please reduce the request frequency, or contact the business representative to adjust the concurrency quota
1402	InsufficientPoints	Insufficient credits	The account balance is insufficient to pay for this task's consumption	Please go to Credit recharge page to recharge credits or upgrade the plan
1403	QuotaErr	No permission	Insufficient plan	Please contact the administrator to enable it, or visit Kickart plan purchase page to subscribe to a plan
1404	QuotaErr	No permission	Insufficient plan	Please contact the administrator to enable it, or visit Kickart plan purchase page to subscribe to a plan
1410	TemplateIdNotExist	Template does not exist	The requested template_id is invalid or the corresponding template is not online	Please confirm whether the template ID is correct (current template ID: 978755330)
1412	ImageFormatErr	Image format error	The input image format is not supported or the file is corrupted	JPEG or PNG format is recommended
1413	InvalidMediaUrlErr	Invalid media URL	Media URL is inaccessible	Please ensure the URL is publicly accessible and has not expired; connecting to Volcano Object Storage is recommended
1418	InvalidDurationBillingErr	Invalid duration parameter	The input duration parameter does not meet the API input requirements	Please check whether the reference video duration meets the requirements (>5 seconds and ≤60 seconds)
1422	GetDouDianProductInfoError	Failed to retrieve product information	The server cannot parse product information from the submitted Douyin Store/Douyin link or product ID	Please confirm that the link is associated with an accessible product, or use a product ID or product image instead; after modification, re-display the final video information and obtain secondary confirmation. Automatic retries are prohibited
1423	VideoResolutionError	Incorrect reference video resolution	The reference video resolution does not meet the requirements	Please check whether the video resolution is ≥480p
1424	VideoDurationError	Incorrect reference video duration	The reference video duration does not meet the requirements	Please check whether the video duration is within the range of >5 seconds and ≤60 seconds
1425	VideoFormatError	Incorrect reference video format	The reference video format is not supported	Please check whether the video format is MP4 or MOV
1426	VideoSizeError	Incorrect reference video size	The reference video file size exceeds the limit	Please check whether the video size is ≤50MB
1427	RefVideoError	Incorrect reference video link	The reference video link is invalid or inaccessible	Please check whether the video URL you provided is correct
1428	LanguageEnumError	Incorrect language enum value	The requested language parameter is not in the supported enum list	Please check whether the language parameter is one of the following valid values: zh, en, en-us, pt-br, ja, es-mx, id, ms, tl
1450	InputValidationErr	Template input parameter validation failed	message will list multiple fields and rules	After correcting as prompted, re-display the final video information and obtain secondary confirmation. Automatic retries are prohibited
1500	InternalErr	Internal error	An unknown error occurred on the server	Please record the request_id and contact technical support
1600	AsyncTaskNotExist	Task does not exist	Invalid task_id	Please check whether the task ID is correct
1601	AsyncTaskTimeoutErr	Task timed out	The task execution exceeded the maximum processing time set by the system (currently 1 hour)	Please contact technical support to verify the task status; if a new task is needed, the final video information must be re-displayed and secondary confirmation obtained
2000	AsyncTaskFailed	Task failed	The task failed during execution	Please check the specific failure reason in message; if a new task is needed after correction, the final video information must be re-displayed and secondary confirmation obtained
x01401	TokenFailed	Failed to obtain token	The current user does not have package permissions	Please contact the administrator to enable it, or visit Kickart package purchase page subscription package