🚨 Mandatory Pre-Check Process
All KickArt operations must first complete the CLI availability and OAuth login status checks:
- KickArt CLI Check
- Read
references/CLI前置校验指南.md。 - Use
command -v npmto check whethernpm execis available. All commands are invoked throughnpm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x kickart-open-cliwith a fixed version, no global or project-level installation required. - Execute
npm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x kickart-open-cli auth_token >/dev/nullto check login status; displaying, logging, or persisting the token is prohibited. - When not yet logged in or credentials are invalid, execute
npm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x kickart-open-cli auth_loginto 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 --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x kickart-open-cli auth_completeonce to obtain the token and complete login, then check 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.
- Read
🎯 Intent Recognition and Task Execution Guide (Automatically recognized based on conversation history)
After determining the intent based on the current user input and historical 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 "check 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 --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.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 Asset Ingestion | When the user explicitly requests "upload to KickArt", "create media asset", "save to asset library", or "query media asset", and it is not providing input assets for a generation task | Read references/素材上传指南.md, execute npm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.x kickart-open-cli material_pipeline_v2 --file-path <绝对路径> |
Output from stdout JSON created.media_id and origin_url |
Images and videos in generation tasks must not trigger this process; local assets are automatically uploaded by the submission command |
| Popular Same-Style | When the user mentions "same-style video", "generate same-style", "popular same-style", or expresses an equivalent intent to create content the same as a certain popular video; also compatibly recognize historical terms such as "viral fission" and "viral clone". | Read references/爆款裂变指南.md, execute npm exec -y --registry=https://registry.npmjs.org --package @volcengine/kickart-open-mcp@1.1.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 Get Result |
You must strictly follow the guide Phase 0 to collect reference videos, product information, and language step by step; optional parameters such as character images, scene images, creative prompt words, 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 reminders must be performed; submission is strictly prohibited before confirmation. |
| Video Reference | When the user proactively provides a reference video, video link, or indicates 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 a trending same-style intent |
| Digital Avatar | When the user mentions "add a 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 trending same-style task |
⚠️ Error Handling Specification
All errors must clearly state the cause and an executable solution; vague prompts are prohibited!!!
General Error Codes
| Error Code | Error Type | Error Description | Detailed Explanation | User Handling Suggestion |
|---|---|---|---|---|
| 0 | Success | Task successful | Task processing completed, results have been generated | - |
| 1000 | AsyncTaskRunning | Task running | The task is being processed, please poll for results 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, execute auth_complete to complete login; automatic retry of paid submission is prohibited, and before resubmitting, the final video information must be displayed again and secondary confirmation obtained |
| 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 upper limit | Please reduce the request frequency, or contact your 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 Credits Recharge Page to recharge credits or upgrade your 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 (Seedance 2.5: 978755330; Seedance 2.0 mini: 1028571394) |
| 1412 | ImageFormatErr | Image format error | The input image format is not supported or the file is corrupted | It is recommended to use JPEG or PNG format |
| 1413 | InvalidMediaUrlErr | Invalid media URL | The 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 the product ID or product image instead; after modification, redisplay the finished 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 | Invalid 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 according to the prompt, redisplay the finished 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 needs to be created, the finished video information must be redisplayed and secondary confirmation obtained |
| 2000 | AsyncTaskFailed | Task failed | The task failed during execution | Please check the specific failure reason in message; if the task needs to be created again after correction, the finished video information must be redisplayed 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 Subscribe to package |