🚨 Mandatory pre-check process
All KickArt operations must first complete the CLI availability and OAuth login status checks:
- KickArt CLI validation
- Read
references/CLI前置校验指南.md。 - Use
command -v npmto check whethernpm execis available. All commands are invoked throughnpm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cliwith 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/nullto check login status. Displaying, logging, or persisting the token is prohibited. - If not yet logged in or the credentials are invalid, execute
npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli auth_loginto obtain the authorization link and show it to the user; this command returns immediately and does not poll the authorization status. - After waiting for the user to explicitly confirm that the web authorization is complete, execute
npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli auth_completeonce 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 the user to provide long-term keys, do not read or echo the OAuth token, and do not directly call 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 history, you must strictly read and follow the corresponding execution basis guide; do not guess the execution steps out of thin air.
| Task type | Triggering 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 --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli query_task_v2 --task-id <ID> --source kickart_ai_material --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 tell the user that no related task was found. |
| Standalone 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. |
| One-click video generation | When the user needs one-click end-to-end generation of a finished video and mentions "one-click video generation", "generate finished video", "generate marketing video", "submit video generation task", or "generate product video". | Read references/一键成片指南.md, execute npm exec -y --package @volcengine/kickart-open-mcp@1.0.x kickart-open-cli submit_marketing_task_v2。 |
Parse the stdout JSON and output the task ID; subsequently obtain the result through query_task_v2 . |
Information must be collected step by step strictly according to Phase 0 of the guide, with the template fixed as 978755842: materials and product information (conditionally required, at least one of the four items), video duration (required, 15/30/45/60 seconds), aspect ratio, language, video purpose, creative instructions, subtitles, subtitle erasure, and visible watermark. All listed optional parameters must be asked about one by one, and before submission, the final video information must be displayed with secondary confirmation and compliance notices. |
| Video reference | When the user proactively provides a 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 a material list that can be passed directly to submit_marketing_task_v2 --user-videos . |
Local video formats MP4/MOV, each ≤50MB; maximum 10. |
⚠️ Error handling specifications
All errors must clearly state the cause and an actionable solution; vague prompts are prohibited.
| Error code | Error type | Error description | Detailed explanation | User handling suggestions |
|---|---|---|---|---|
| 0 | Success | Task successful | Task processing completed, result has been generated | - |
| 1000 | AsyncTaskRunning | Task running | The 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, execute auth_complete to complete login; automatic retry of paid submission is prohibited, and before resubmission 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 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: 978755842) |
| 1412 | ImageFormatErr | Image format error | The input image format is unsupported or the file is corrupted | JPEG or PNG format is recommended |
| 1413 | InvalidMediaUrlErr | Invalid media URL | The media URL is inaccessible | Please ensure the URL is publicly reachable 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, display the finished video information again and obtain secondary confirmation. Do not retry automatically. |
| 1423 | VideoResolutionError | Reference video resolution error | The reference video resolution does not meet the requirements | Please check whether the video resolution is ≥480p |
| 1424 | VideoDurationError | Reference video duration error | 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 | Reference video format error | The reference video format is not supported | Please check whether the video format is MP4 or MOV |
| 1426 | VideoSizeError | Video size error | The local video file size exceeds the media asset tool limit | Please check whether the video size is ≤50MB |
| 1427 | RefVideoError | Reference video link error | The reference video link is invalid or inaccessible | Please check whether the video URL you provided is correct |
| 1428 | LanguageEnumError | Language enum value error | 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 | The message will list multiple fields and rules | After correcting according to the prompt, display the finished video information again and obtain secondary confirmation. Do not retry automatically. |
| 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 | task_id is invalid | Please check whether the task ID is correct |
| 1601 | AsyncTaskTimeoutErr | Task timed out | The task execution exceeded the system's maximum processing time (currently 1 hour) | Please contact technical support to verify the task status; if a new task needs to be created, you must display the finished video information again and obtain secondary confirmation |
| 2000 | AsyncTaskFailed | Task failed | The task failed during execution | Please check the specific failure reason in the message; if a new task needs to be created after correction, you must display the finished video information again and obtain secondary confirmation |
| x01401 | TokenFailed | Token retrieval failed | The current user does not have package permissions | Please contact the administrator to enable it, or visit Kickart package purchase page to subscribe to a package |