🚨 Mandatory Pre-check Process
All KickArt operations must first complete the CLI availability and OAuth login state checks:
- KickArt CLI Verification
- Read
references/CLI前置校验指南.md。 - Use
command -v npmto check whethernpm execis available. - All commands must use
npm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x -- kickart-open-cli。 - Execute
auth_token >/dev/nullto check the login state; displaying, logging, or persisting the token is prohibited. - If not yet logged in or credentials are invalid, execute
auth_loginto obtain an 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
auth_completea single time to obtain the token and complete login, then check the login state again; automatic polling or execution before user confirmation is prohibited. - If npm exec fails to download the package or the CLI is still unavailable, provide 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.
- Read
🎯 Intent Recognition and Task Execution Guide
After determining the intent based on the current user input and history, you must strictly read and follow the corresponding execution basis guide; do not guess the execution steps out of thin air.
| Task Type | Trigger Intent and Keywords | Execution Basis | Output Requirements | Prerequisites |
|---|---|---|---|---|
| Progress Query | The user mentions "query progress", "view results", "how is the generation going", "is it done", or queries a specific task ID | Read references/任务查询指南.md, execute query_task_v2 |
Parse the stdout JSON and output the current status or result | The task ID must be obtained from the session context |
| Video Element Replacement | The user mentions "replace character", "replace scene", "replace product", "replace prop", "replace sound", "video element replacement", etc. | Read references/视频元素替换指南.md, execute submit_high_similarity_task_v2 |
Parse the stdout JSON and output the task ID; subsequently obtain the result through query_task_v2 Get result |
Must gradually collect the reference video, language, model, replacement assets, and creative prompt, and complete two submission confirmations |
| Video Reference | The user proactively provides a reference video, video link, or indicates they want to upload a video | Read references/视频参考指南.md |
Obtain asset values that can be passed directly to --ref-video asset value |
The primary prerequisite step for video element replacement |
| Replacement Assets | The user proactively provides replacement character, scene, product, or prop images, or requests replacement of non-image elements such as sound | Read references/替换图片指南.md |
Obtain the image list arranged in the user's order that can be passed directly to --replace-images ; other elements are described through --prompt Description |
Must confirm the receiving order item by item; the replacement relationships are explained in the creative prompt |
⚠️ Error Handling Specifications
All errors must clearly state the reason and an executable solution; vague prompts are prohibited.
| Error code | Error type | Error description | User handling suggestion |
|---|---|---|---|
| 0 | Success | Task succeeded, result has been generated | - |
| 1000 | AsyncTaskRunning | Task is being processed | Get the result later via task query |
| 1300 | AuthFailed | OAuth authentication failed | Execute in sequence auth_login, wait for web authorization, execute auth_complete; automatic retry of paid submission is prohibited |
| 1400 | ParamErr | Parameter error | Follow CLI --help to check fields and required items |
| 1401 | ConcurrentErr | Concurrency limit exceeded | Reduce request frequency or contact the administrator |
| 1402 | InsufficientPoints | Insufficient credits | Recharge credits or upgrade the plan; do not continue submitting |
| 1403 | QuotaErr | Insufficient plan or permissions | Contact the administrator to enable permissions |
| 1410 | TemplateIdNotExist | Template does not exist | Confirm whether --template-id is a template supported by the server; Seedance 2.5 uses 978755330, and Seedance 2.0 mini uses 1028571394 |
| 1412 | ImageFormatErr | Image format error | Use a JPEG or PNG image |
| 1413 | InvalidMediaUrlErr | Media URL is invalid | Ensure the URL is publicly accessible and not expired |
| 1418 | InvalidDurationBillingErr | Input video duration does not meet requirements | Replace the reference video according to the server error prompt |
| 1423 | VideoResolutionError | Video resolution error | Provide a reference video that meets the server requirements |
| 1424 | VideoDurationError | Video duration error | Replace with a reference video that meets the server requirements |
| 1425 | VideoFormatError | Video format not supported | Use an MP4 or MOV video |
| 1426 | VideoSizeError | Video size exceeds the limit | Compress the video and provide it again |
| 1427 | RefVideoError | Reference video link error | Check whether the URL is valid |
| 1428 | LanguageEnumError | Language parameter error | Use zh、en、en-us、pt-br、ja、es-mx、id、ms or tl |
| 1450 | InputValidationErr | Template input parameter validation failed | Correct the parameters according to message, confirm again, and then submit |
| 1500 | InternalErr | Server internal error | Record the desensitized request_id and contact technical support |
| 1600 | AsyncTaskNotExist | Task does not exist | Check the task ID |
| 1601 | AsyncTaskTimeoutErr | Task timed out | Contact technical support; a new task must be confirmed again |
| 2000 | AsyncTaskFailed | Task failed | Correct the issue according to message; automatic retry of paid tasks is prohibited |
Security and submission rules
- Reference videos, replacement assets, and creative content must have authorization for lawful use, adaptation, and commercial publication.
- Submission is allowed only after the user completes final video information confirmation and deduction, and a second compliance confirmation.
submit_high_similarity_task_v2will create a paid asynchronous task, does not guarantee idempotency, and automatic retry is prohibited in any failure scenario.- When it cannot be confirmed whether the request has been accepted, do not submit again; if there is
task_id, query according to the task query guide. - After successful submission, return the real
task_id, and do not describe "submitted" as "generated".