{ "schemaVersion": "1.0", "item": { "slug": "acestep", "name": "acestep", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/DumoeDss/acestep", "canonicalUrl": "https://clawhub.ai/DumoeDss/acestep", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/acestep", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=acestep", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "api-reference.md", "scripts/acestep.sh", "scripts/config.example.json", "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-07T17:22:31.273Z", "expiresAt": "2026-05-14T17:22:31.273Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/acestep" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/acestep", "agentPageUrl": "https://openagent3.xyz/skills/acestep/agent", "manifestUrl": "https://openagent3.xyz/skills/acestep/agent.json", "briefUrl": "https://openagent3.xyz/skills/acestep/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "ACE-Step Music Generation Skill", "body": "Use ACE-Step V1.5 API for music generation. Always use scripts/acestep.sh script — do NOT call API endpoints directly." }, { "title": "Quick Start", "body": "# 1. cd to this skill's directory\ncd {project_root}/{.claude or .codex}/skills/acestep/\n\n# 2. Check API service health\n./scripts/acestep.sh health\n\n# 3. Generate with lyrics (recommended)\n./scripts/acestep.sh generate -c \"pop, female vocal, piano\" -l \"[Verse] Your lyrics here...\" --duration 120 --language zh\n\n# 4. Output saved to: {project_root}/acestep_output/" }, { "title": "Workflow", "body": "For user requests requiring vocals:\n\nUse the acestep-songwriting skill for lyrics writing, caption creation, duration/BPM/key selection\nWrite complete, well-structured lyrics yourself based on the songwriting guide\nGenerate using Caption mode with -c and -l parameters\n\nOnly use Simple/Random mode (-d or random) for quick inspiration or instrumental exploration.\n\nIf the user needs a simple music video, use the acestep-simplemv skill to render one with waveform visualization and synced lyrics.\n\nMV Production Requirements: Making a simple MV requires three additional skills to be installed:\n\nacestep-songwriting — for writing lyrics and planning song structure\nacestep-lyrics-transcription — for transcribing audio to timestamped lyrics (LRC)\nacestep-simplemv — for rendering the final music video" }, { "title": "Script Commands", "body": "CRITICAL - Complete Lyrics Input: When providing lyrics via the -l parameter, you MUST pass ALL lyrics content WITHOUT any omission:\n\nIf user provides lyrics, pass the ENTIRE text they give you\nIf you generate lyrics yourself, pass the COMPLETE lyrics you created\nNEVER truncate, shorten, or pass only partial lyrics\nMissing lyrics will result in incomplete or incoherent songs\n\nMusic Parameters: Use the acestep-songwriting skill for guidance on duration, BPM, key scale, and time signature.\n\n# need to cd to this skill's directory first\ncd {project_root}/{.claude or .codex}/skills/acestep/\n\n# Caption mode - RECOMMENDED: Write lyrics first, then generate\n./scripts/acestep.sh generate -c \"Electronic pop, energetic synths\" -l \"[Verse] Your complete lyrics\n[Chorus] Full chorus here...\" --duration 120 --bpm 128\n\n# Instrumental only\n./scripts/acestep.sh generate \"Jazz with saxophone\"\n\n# Quick exploration (Simple/Random mode)\n./scripts/acestep.sh generate -d \"A cheerful song about spring\"\n./scripts/acestep.sh random\n\n# Options\n./scripts/acestep.sh generate \"Rock\" --duration 60 --batch 2\n./scripts/acestep.sh generate \"EDM\" --no-thinking # Faster\n\n# Other commands\n./scripts/acestep.sh status \n./scripts/acestep.sh health\n./scripts/acestep.sh models" }, { "title": "Output Files", "body": "After generation, the script automatically saves results to the acestep_output folder in the project root (same level as .claude):\n\nproject_root/\n├── .claude/\n│ └── skills/acestep/...\n├── acestep_output/ # Output directory\n│ ├── .json # Complete task result (JSON)\n│ ├── _1.mp3 # First audio file\n│ ├── _2.mp3 # Second audio file (if batch_size > 1)\n│ └── ...\n└── ..." }, { "title": "JSON Result Structure", "body": "Important: When LM enhancement is enabled (use_format=true), the final synthesized content may differ from your input. Check the JSON file for actual values:\n\nFieldDescriptionpromptActual caption used for synthesis (may be LM-enhanced)lyricsActual lyrics used for synthesis (may be LM-enhanced)metas.promptOriginal input captionmetas.lyricsOriginal input lyricsmetas.bpmBPM usedmetas.keyscaleKey scale usedmetas.durationDuration in secondsgeneration_infoDetailed timing and model infoseed_valueSeeds used (for reproducibility)lm_modelLM model namedit_modelDiT model name\n\nTo get the actual synthesized lyrics, parse the JSON and read the top-level lyrics field, not metas.lyrics." }, { "title": "Configuration", "body": "Important: Configuration follows this priority (high to low):\n\nCommand line arguments > config.json defaults\nUser-specified parameters temporarily override defaults but do not modify config.json\nOnly config --set command permanently modifies config.json" }, { "title": "Default Config File (scripts/config.json)", "body": "{\n \"api_url\": \"http://127.0.0.1:8001\",\n \"api_key\": \"\",\n \"api_mode\": \"completion\",\n \"generation\": {\n \"thinking\": true,\n \"use_format\": false,\n \"use_cot_caption\": true,\n \"use_cot_language\": false,\n \"batch_size\": 1,\n \"audio_format\": \"mp3\",\n \"vocal_language\": \"en\"\n }\n}\n\nOptionDefaultDescriptionapi_urlhttp://127.0.0.1:8001API server addressapi_key\"\"API authentication key (optional)api_modecompletionAPI mode: completion (OpenRouter, default) or native (polling)generation.thinkingtrueEnable 5Hz LM (higher quality, slower)generation.audio_formatmp3Output format (mp3/wav/flac)generation.vocal_languageenVocal language" }, { "title": "Prerequisites - ACE-Step API Service", "body": "IMPORTANT: This skill requires the ACE-Step API server to be running." }, { "title": "Required Dependencies", "body": "The scripts/acestep.sh script requires: curl and jq.\n\n# Check dependencies\ncurl --version\njq --version\n\nIf jq is not installed, the script will attempt to install it automatically. If automatic installation fails:\n\nWindows: choco install jq or download from https://jqlang.github.io/jq/download/\nmacOS: brew install jq\nLinux: sudo apt-get install jq (Debian/Ubuntu) or sudo dnf install jq (Fedora)" }, { "title": "Before First Use", "body": "You MUST check the API key and URL status before proceeding. Run:\n\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --check-key\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --get api_url\n\nCase 1: Using Official Cloud API (https://api.acemusic.ai) without API key\n\nIf api_url is https://api.acemusic.ai and api_key is empty, you MUST stop and guide the user to configure their key:\n\nTell the user: \"You're using the ACE-Step official cloud API, but no API key is configured. An API key is required to use this service.\"\nExplain how to get a key: API keys are currently available through acemusic.ai for free.\nUse AskUserQuestion to ask the user to provide their API key.\nOnce provided, configure it:\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --set api_key \n\n\nAdditionally, inform the user: \"If you also want to render music videos (MV), it's recommended to configure a lyrics transcription API key as well (OpenAI Whisper or ElevenLabs Scribe), so that lyrics can be automatically transcribed with accurate timestamps. You can configure it later via the acestep-lyrics-transcription skill.\"\n\nCase 2: API key is configured\n\nVerify the API endpoint: ./scripts/acestep.sh health and proceed with music generation.\n\nCase 3: Using local/custom API without key\n\nLocal services (http://127.0.0.1:*) typically don't require a key. Verify with ./scripts/acestep.sh health and proceed.\n\nIf health check fails:\n\nAsk: \"Do you have ACE-Step installed?\"\nIf installed but not running: Use the acestep-docs skill to help them start the service\nIf not installed: Use acestep-docs skill to guide through installation" }, { "title": "Service Configuration", "body": "Official Cloud API: ACE-Step provides an official API endpoint at https://api.acemusic.ai. To use it:\n\n./scripts/acestep.sh config --set api_url \"https://api.acemusic.ai\"\n./scripts/acestep.sh config --set api_key \"your-key\"\n./scripts/acestep.sh config --set api_mode completion\n\nAPI keys are currently available through acemusic.ai for free.\n\nLocal Service (Default): No configuration needed — connects to http://127.0.0.1:8001.\n\nCustom Remote Service: Update scripts/config.json or use:\n\n./scripts/acestep.sh config --set api_url \"http://remote-server:8001\"\n./scripts/acestep.sh config --set api_key \"your-key\"\n\nAPI Key Handling: When checking whether an API key is configured, use config --check-key which only reports configured or empty without printing the actual key. NEVER use config --get api_key or read config.json directly — these would expose the user's API key. The config --list command is safe — it automatically masks API keys as *** in output." }, { "title": "API Mode", "body": "The skill supports two API modes. Switch via api_mode in scripts/config.json:\n\nModeEndpointDescriptioncompletion (default)/v1/chat/completionsOpenRouter-compatible, sync request, audio returned as base64native/release_task + /query_resultAsync polling mode, supports all parameters\n\nSwitch mode:\n\n./scripts/acestep.sh config --set api_mode completion\n./scripts/acestep.sh config --set api_mode native\n\nCompletion mode notes:\n\nNo polling needed — single request returns result directly\nAudio is base64-encoded inline in the response (auto-decoded and saved)\ninference_steps, infer_method, shift are not configurable (server defaults)\n--no-wait and status commands are not applicable in completion mode\nRequires model field — auto-detected from /v1/models if not specified" }, { "title": "Using acestep-docs Skill for Setup Help", "body": "IMPORTANT: For installation and startup, always use the acestep-docs skill to get complete and accurate guidance.\n\nDO NOT provide simplified startup commands - each user's environment may be different. Always guide them to use acestep-docs for proper setup.\n\nFor API debugging, see API Reference." } ], "body": "ACE-Step Music Generation Skill\n\nUse ACE-Step V1.5 API for music generation. Always use scripts/acestep.sh script — do NOT call API endpoints directly.\n\nQuick Start\n# 1. cd to this skill's directory\ncd {project_root}/{.claude or .codex}/skills/acestep/\n\n# 2. Check API service health\n./scripts/acestep.sh health\n\n# 3. Generate with lyrics (recommended)\n./scripts/acestep.sh generate -c \"pop, female vocal, piano\" -l \"[Verse] Your lyrics here...\" --duration 120 --language zh\n\n# 4. Output saved to: {project_root}/acestep_output/\n\nWorkflow\n\nFor user requests requiring vocals:\n\nUse the acestep-songwriting skill for lyrics writing, caption creation, duration/BPM/key selection\nWrite complete, well-structured lyrics yourself based on the songwriting guide\nGenerate using Caption mode with -c and -l parameters\n\nOnly use Simple/Random mode (-d or random) for quick inspiration or instrumental exploration.\n\nIf the user needs a simple music video, use the acestep-simplemv skill to render one with waveform visualization and synced lyrics.\n\nMV Production Requirements: Making a simple MV requires three additional skills to be installed:\n\nacestep-songwriting — for writing lyrics and planning song structure\nacestep-lyrics-transcription — for transcribing audio to timestamped lyrics (LRC)\nacestep-simplemv — for rendering the final music video\nScript Commands\n\nCRITICAL - Complete Lyrics Input: When providing lyrics via the -l parameter, you MUST pass ALL lyrics content WITHOUT any omission:\n\nIf user provides lyrics, pass the ENTIRE text they give you\nIf you generate lyrics yourself, pass the COMPLETE lyrics you created\nNEVER truncate, shorten, or pass only partial lyrics\nMissing lyrics will result in incomplete or incoherent songs\n\nMusic Parameters: Use the acestep-songwriting skill for guidance on duration, BPM, key scale, and time signature.\n\n# need to cd to this skill's directory first\ncd {project_root}/{.claude or .codex}/skills/acestep/\n\n# Caption mode - RECOMMENDED: Write lyrics first, then generate\n./scripts/acestep.sh generate -c \"Electronic pop, energetic synths\" -l \"[Verse] Your complete lyrics\n[Chorus] Full chorus here...\" --duration 120 --bpm 128\n\n# Instrumental only\n./scripts/acestep.sh generate \"Jazz with saxophone\"\n\n# Quick exploration (Simple/Random mode)\n./scripts/acestep.sh generate -d \"A cheerful song about spring\"\n./scripts/acestep.sh random\n\n# Options\n./scripts/acestep.sh generate \"Rock\" --duration 60 --batch 2\n./scripts/acestep.sh generate \"EDM\" --no-thinking # Faster\n\n# Other commands\n./scripts/acestep.sh status \n./scripts/acestep.sh health\n./scripts/acestep.sh models\n\nOutput Files\n\nAfter generation, the script automatically saves results to the acestep_output folder in the project root (same level as .claude):\n\nproject_root/\n├── .claude/\n│ └── skills/acestep/...\n├── acestep_output/ # Output directory\n│ ├── .json # Complete task result (JSON)\n│ ├── _1.mp3 # First audio file\n│ ├── _2.mp3 # Second audio file (if batch_size > 1)\n│ └── ...\n└── ...\n\nJSON Result Structure\n\nImportant: When LM enhancement is enabled (use_format=true), the final synthesized content may differ from your input. Check the JSON file for actual values:\n\nField\tDescription\nprompt\tActual caption used for synthesis (may be LM-enhanced)\nlyrics\tActual lyrics used for synthesis (may be LM-enhanced)\nmetas.prompt\tOriginal input caption\nmetas.lyrics\tOriginal input lyrics\nmetas.bpm\tBPM used\nmetas.keyscale\tKey scale used\nmetas.duration\tDuration in seconds\ngeneration_info\tDetailed timing and model info\nseed_value\tSeeds used (for reproducibility)\nlm_model\tLM model name\ndit_model\tDiT model name\n\nTo get the actual synthesized lyrics, parse the JSON and read the top-level lyrics field, not metas.lyrics.\n\nConfiguration\n\nImportant: Configuration follows this priority (high to low):\n\nCommand line arguments > config.json defaults\nUser-specified parameters temporarily override defaults but do not modify config.json\nOnly config --set command permanently modifies config.json\nDefault Config File (scripts/config.json)\n{\n \"api_url\": \"http://127.0.0.1:8001\",\n \"api_key\": \"\",\n \"api_mode\": \"completion\",\n \"generation\": {\n \"thinking\": true,\n \"use_format\": false,\n \"use_cot_caption\": true,\n \"use_cot_language\": false,\n \"batch_size\": 1,\n \"audio_format\": \"mp3\",\n \"vocal_language\": \"en\"\n }\n}\n\nOption\tDefault\tDescription\napi_url\thttp://127.0.0.1:8001\tAPI server address\napi_key\t\"\"\tAPI authentication key (optional)\napi_mode\tcompletion\tAPI mode: completion (OpenRouter, default) or native (polling)\ngeneration.thinking\ttrue\tEnable 5Hz LM (higher quality, slower)\ngeneration.audio_format\tmp3\tOutput format (mp3/wav/flac)\ngeneration.vocal_language\ten\tVocal language\nPrerequisites - ACE-Step API Service\n\nIMPORTANT: This skill requires the ACE-Step API server to be running.\n\nRequired Dependencies\n\nThe scripts/acestep.sh script requires: curl and jq.\n\n# Check dependencies\ncurl --version\njq --version\n\n\nIf jq is not installed, the script will attempt to install it automatically. If automatic installation fails:\n\nWindows: choco install jq or download from https://jqlang.github.io/jq/download/\nmacOS: brew install jq\nLinux: sudo apt-get install jq (Debian/Ubuntu) or sudo dnf install jq (Fedora)\nBefore First Use\n\nYou MUST check the API key and URL status before proceeding. Run:\n\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --check-key\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --get api_url\n\nCase 1: Using Official Cloud API (https://api.acemusic.ai) without API key\n\nIf api_url is https://api.acemusic.ai and api_key is empty, you MUST stop and guide the user to configure their key:\n\nTell the user: \"You're using the ACE-Step official cloud API, but no API key is configured. An API key is required to use this service.\"\nExplain how to get a key: API keys are currently available through acemusic.ai for free.\nUse AskUserQuestion to ask the user to provide their API key.\nOnce provided, configure it:\ncd \"{project_root}/{.claude or .codex}/skills/acestep/\" && bash ./scripts/acestep.sh config --set api_key \n\nAdditionally, inform the user: \"If you also want to render music videos (MV), it's recommended to configure a lyrics transcription API key as well (OpenAI Whisper or ElevenLabs Scribe), so that lyrics can be automatically transcribed with accurate timestamps. You can configure it later via the acestep-lyrics-transcription skill.\"\nCase 2: API key is configured\n\nVerify the API endpoint: ./scripts/acestep.sh health and proceed with music generation.\n\nCase 3: Using local/custom API without key\n\nLocal services (http://127.0.0.1:*) typically don't require a key. Verify with ./scripts/acestep.sh health and proceed.\n\nIf health check fails:\n\nAsk: \"Do you have ACE-Step installed?\"\nIf installed but not running: Use the acestep-docs skill to help them start the service\nIf not installed: Use acestep-docs skill to guide through installation\nService Configuration\n\nOfficial Cloud API: ACE-Step provides an official API endpoint at https://api.acemusic.ai. To use it:\n\n./scripts/acestep.sh config --set api_url \"https://api.acemusic.ai\"\n./scripts/acestep.sh config --set api_key \"your-key\"\n./scripts/acestep.sh config --set api_mode completion\n\n\nAPI keys are currently available through acemusic.ai for free.\n\nLocal Service (Default): No configuration needed — connects to http://127.0.0.1:8001.\n\nCustom Remote Service: Update scripts/config.json or use:\n\n./scripts/acestep.sh config --set api_url \"http://remote-server:8001\"\n./scripts/acestep.sh config --set api_key \"your-key\"\n\n\nAPI Key Handling: When checking whether an API key is configured, use config --check-key which only reports configured or empty without printing the actual key. NEVER use config --get api_key or read config.json directly — these would expose the user's API key. The config --list command is safe — it automatically masks API keys as *** in output.\n\nAPI Mode\n\nThe skill supports two API modes. Switch via api_mode in scripts/config.json:\n\nMode\tEndpoint\tDescription\ncompletion (default)\t/v1/chat/completions\tOpenRouter-compatible, sync request, audio returned as base64\nnative\t/release_task + /query_result\tAsync polling mode, supports all parameters\n\nSwitch mode:\n\n./scripts/acestep.sh config --set api_mode completion\n./scripts/acestep.sh config --set api_mode native\n\n\nCompletion mode notes:\n\nNo polling needed — single request returns result directly\nAudio is base64-encoded inline in the response (auto-decoded and saved)\ninference_steps, infer_method, shift are not configurable (server defaults)\n--no-wait and status commands are not applicable in completion mode\nRequires model field — auto-detected from /v1/models if not specified\nUsing acestep-docs Skill for Setup Help\n\nIMPORTANT: For installation and startup, always use the acestep-docs skill to get complete and accurate guidance.\n\nDO NOT provide simplified startup commands - each user's environment may be different. Always guide them to use acestep-docs for proper setup.\n\nFor API debugging, see API Reference." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/DumoeDss/acestep", "publisherUrl": "https://clawhub.ai/DumoeDss/acestep", "owner": "DumoeDss", "version": "1.0.2", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/acestep", "downloadUrl": "https://openagent3.xyz/downloads/acestep", "agentUrl": "https://openagent3.xyz/skills/acestep/agent", "manifestUrl": "https://openagent3.xyz/skills/acestep/agent.json", "briefUrl": "https://openagent3.xyz/skills/acestep/agent.md" } }