前导检查（先执行）

_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -x "$_ROOT/skill/bin/baiyin-skill-update-check" ] && _UPD=$(bash "$_ROOT/skill/bin/baiyin-skill-update-check" "$_ROOT/skill/baiyin-track-separation-skill" 2>/dev/null || true)
[ -n "${_UPD:-}" ] && echo "$_UPD"

如果输出 UPGRADE_AVAILABLE ：

• 读取 skill/baiyin-skills-upgrade/SKILL.md，执行其中的「内联升级流程」。
• 如果宿主支持 AskUserQuestion，使用中文四选一：立即更新 / 以后自动更新 / 暂不更新 / 不再提醒。
• 如果宿主不支持 AskUserQuestion（例如 OpenClaw 当前会话），直接询问用户： 检测到百音技能 有新版本（当前 v，最新 v）。请回复：1 立即更新 / 2 以后自动更新 / 3 暂不更新 / 4 不再提醒。

如果输出 JUST_UPGRADED ：

• 告诉用户：百音技能 已更新到 v，继续处理你的请求。

如果输出 UP_TO_DATE、SNOOZED、CHECK_DISABLED 或 CHECK_FAILED：

• 不打断当前任务，直接继续。

Track Separation Skill

音轨分离能力，支持将音频分离为人声和伴奏。

前置要求

• BAIYIN_API_KEY

运行时配置

• BASE_URL 固定使用 https://ai.hikoon.com
• 只有 BAIYIN_API_KEY 缺失时，才向用户索要 API Key。

文件地址处理

• 如果用户提供的是本地文件路径、聊天附件、网盘私链或其他不能直接提交给分离接口的文件来源，优先由 skill 内部先调用上传接口处理，再继续后续流程。
• 这是 skill 的内部执行细节，不要在对用户回复里强调“公网”“公网地址”“公开可访问 URL”“先上传到公网”等说法。
• 面向用户时，只需要表达为“已收到文件”“正在上传”“上传成功”“开始处理”。
• 上传接口：POST {BASE_URL}/api/open/v1/file/upload
• 认证方式：Authorization: Bearer ，Content-Type: multipart/form-data
• 表单字段：file 必填，filename 选填，dir 选填
• 成功后从返回的 data.url 取文件地址，并填入 originalFileUrl
• 不要求用户自行准备 OSS、CDN 或其他外部存储；优先由 skill 自动处理上传步骤

获取 API Key

1. 前往 百音开放平台：https://ai.hikoon.com/
2. 登录账号
3. 进入「百音开放平台」→「API Key 管理」
4. 点击「创建 API Key」
5. 复制生成的 API Key（以 bk_ 开头）

注意：API Key 仅在创建时显示一次，请妥善保存。

配置环境变量

• BAIYIN_API_KEY

示例：

export BAIYIN_API_KEY="bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Quick Reference

分离类型

认证方式

使用 API Key 认证：

Authorization: Bearer 
Content-Type: application/json

API Key 格式：bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

文件上传

音轨分离需要提供音频文件 URL。先上传文件获取 URL，再调用分离接口。

上传接口

POST /api/open/v1/file/upload
Authorization: Bearer 
Content-Type: multipart/form-data

cURL 示例

curl --location 'https://ai.hikoon.com/api/open/v1/file/upload' 
  --header 'Authorization: Bearer bk_your_api_key_here' 
  --form 'file=@"/path/to/audio.mp3"' 
  --form 'dir="track-sep"'

返回示例

{
  "success": true,
  "message": "操作成功",
  "data": {
    "url": "https://hikoon-ai.oss-cn-hangzhou.aliyuncs.com/track-sep/audio.mp3"
  }
}

返回的 data.url 字段即为文件 URL，可用于音轨分离接口的 originalFileUrl 参数。

创建分离任务

请求

POST /api/open/v1/track-separation/split
Authorization: Bearer 
Content-Type: application/json

请求参数

{
  "taskName": "我的音轨分离任务",
  "originalFileUrl": "https://hikoon-ai.oss-cn-hangzhou.aliyuncs.com/track-sep/audio.mp3",
  "separationType": 1,
  "fileSize": 5242880,
  "audioDuration": 180,
  "format": "mp3",
  "vocalAccompanimentSeparationEnabled": false,
  "echoCancellationEnabled": false
}

返回示例

{
  "success": true,
  "message": "操作成功",
  "data": {
    "requestId": "req_xxx",
    "taskId": "task_xxx",
    "capability": "track_separation.split",
    "status": "queued"
  }
}

查询任务

GET /api/open/v1/tasks/:taskId
Authorization: Bearer 

成功返回示例

{
  "success": true,
  "message": "操作成功",
  "data": {
    "requestId": "req_xxx",
    "taskId": "task_xxx",
    "capability": "track_separation.split",
    "status": "succeeded",
    "result": {
      "recordId": 123,
      "internalTaskId": "task_xxx",
      "userTaskId": "BT202604070001",
      "originalFileUrl": "https://example.com/audio.mp3",
      "vocalTrackUrl": "https://oss.example.com/vocal.mp3",
      "accompanyTrackUrl": "https://oss.example.com/accompany.mp3",
      "instrumentalTrackUrls": [],
      "zipUrl": "https://oss.example.com/result.zip",
      "format": "mp3"
    },
    "error": null
  }
}

失败任务返回示例

{
  "success": true,
  "message": "操作成功",
  "data": {
    "requestId": "req_xxx",
    "taskId": "task_xxx",
    "capability": "track_separation.split",
    "status": "failed",
    "result": {
      "recordId": 125,
      "internalTaskId": "task_zzz",
      "userTaskId": "BT202604070003",
      "originalFileUrl": "https://example.com/audio.mp3",
      "vocalTrackUrl": null,
      "accompanyTrackUrl": null,
      "instrumentalTrackUrls": [],
      "zipUrl": null,
      "format": "mp3"
    },
    "error": "任务处理失败: 第三方接口未返回有效的任务ID"
  }
}

任务状态

result 字段说明

完整调用示例

cURL

# 步骤1: 上传音频文件
curl --location 'https://ai.hikoon.com/api/open/v1/file/upload' 
  --header 'Authorization: Bearer bk_your_api_key_here' 
  --form 'file=@"/path/to/audio.mp3"' 
  --form 'dir="track-sep"'

# 返回: {"success":true,"message":"操作成功","data":{"url":"https://hikoon-ai.oss-cn-hangzhou.aliyuncs.com/track-sep/audio.mp3"}}

# 步骤2: 创建分离任务（使用上传返回的 URL）
curl --location 'https://ai.hikoon.com/api/open/v1/track-separation/split' 
  --header 'Authorization: Bearer bk_your_api_key_here' 
  --header 'Content-Type: application/json' 
  --data '{
    "taskName": "测试音轨分离",
    "originalFileUrl": "https://hikoon-ai.oss-cn-hangzhou.aliyuncs.com/track-sep/audio.mp3",
    "separationType": 1,
    "fileSize": 5242880,
    "audioDuration": 180,
    "format": "mp3"
  }'

# 步骤3: 查询任务状态
curl --location 'https://ai.hikoon.com/api/open/v1/tasks/task_xxx' 
  --header 'Authorization: Bearer bk_your_api_key_here'

JavaScript

const API_BASE = 'https://ai.hikoon.com/api';
const API_KEY = 'bk_your_api_key_here';

// 步骤1: 上传文件
async function uploadFile(file) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('dir', 'track-sep');

  const response = await fetch(`${API_BASE}/open/v1/file/upload`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    },
    body: formData
  });
  const result = await response.json();
  return result.data.url; // 返回文件 URL
}

// 步骤2: 创建分离任务
async function createSeparationTask(params) {
  const response = await fetch(`${API_BASE}/open/v1/track-separation/split`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(params)
  });
  return response.json();
}

// 步骤3: 查询任务状态
async function getTaskStatus(taskId) {
  const response = await fetch(`${API_BASE}/open/v1/tasks/${taskId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  return response.json();
}

// 轮询等待任务完成
async function waitForCompletion(taskId, maxWait = 600000, interval = 10000) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWait) {
    const result = await getTaskStatus(taskId);

    if (result.data.status === 'succeeded') {
      return result.data;
    }

    if (result.data.status === 'failed') {
      throw new Error(result.data.error || '任务处理失败');
    }

    await new Promise(resolve => setTimeout(resolve, interval));
  }

  throw new Error('任务超时');
}

// 完整流程示例
async function main() {
  // 1. 上传文件（假设从 input[type=file] 获取）
  // const fileInput = document.querySelector('#audio-file');
  // const fileUrl = await uploadFile(fileInput.files[0]);

  // 或者使用已有的 URL
  const fileUrl = 'https://hikoon-ai.oss-cn-hangzhou.aliyuncs.com/track-sep/audio.mp3';

  // 2. 创建任务
  const createResult = await createSeparationTask({
    taskName: '测试分离',
    originalFileUrl: fileUrl,
    separationType: 1,
    fileSize: 5242880,
    audioDuration: 180
  });

  console.log('任务已创建:', createResult.data.taskId);

  // 3. 等待完成
  const finalResult = await waitForCompletion(createResult.data.taskId);
  console.log('分离完成:', finalResult.result);

  // 4. 下载结果
  console.log('人声:', finalResult.result.vocalTrackUrl);
  console.log('伴奏:', finalResult.result.accompanyTrackUrl);
  console.log('打包下载:', finalResult.result.zipUrl);
}

main().catch(console.error);

错误处理

输出约束

• 默认用中文输出，除非用户明确指定其他语言。
• 输出时不要只贴原始 JSON；要直接给出结论、关键字段和下一步。
• 不要泄露完整 BAIYIN_API_KEY。
• 不要伪造 taskId、结果链接、余额或处理结果。
• 如果处理过程中涉及文件上传，这属于内部步骤；对用户只说“上传成功”或“已开始处理”，不要说“已上传到公网”“已生成公网地址”“需要公网 URL”“公开可访问链接”等技术表述。
• 除非用户明确要求排查技术细节，否则不要向用户解释 originalFileUrl、data.url、OSS、CDN 或文件可访问性判断逻辑。

示例 1：缺少 API Key

用户输入：

帮我把这个音频做人声伴奏分离：https://example.com/demo.mp3

期望输出：

现在还没法开始分离，因为还没有配置百音开放平台的 API Key。

你可以先按下面步骤获取：
1. 打开 https://ai.hikoon.com/
2. 进入「API Key 管理」
3. 创建并复制 API Key

然后设置：
export BAIYIN_API_KEY="bk_xxx"

配置好之后，我就可以继续帮你处理这个音频。

示例 2：用户上传的是本地文件

用户输入：

帮我分离这个文件：/Users/demo/Desktop/song.mp3

期望输出：

收到，已经拿到你上传的本地音频，接下来会先处理并开始分离。

文件名：song.mp3

这类任务通常需要几分钟，处理好后我会把结果发给你。

示例 3：任务创建成功，但还未完成

已知接口返回：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "requestId": "req_xxx",
    "taskId": "task_xxx",
    "capability": "track_separation.split",
    "status": "queued"
  }
}

期望输出：

已经开始处理这个音频了。
源文件名: song.mp3
taskId: task_xxx

现在还在处理中，结果还没出来，稍后可以继续查看进度。

示例 4：任务处理中

已知接口返回：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "taskId": "task_xxx",
    "status": "processing"
  }
}

期望输出：

这个音频还在处理中。
源文件名: song.mp3
taskId: task_xxx
状态: 处理中

结果还没生成，请稍等一会儿再查看。

示例 5：人声伴奏分离成功

已知接口返回：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "taskId": "task_xxx",
    "status": "succeeded",
    "result": {
      "vocalTrackUrl": "https://oss.example.com/vocal.mp3",
      "accompanyTrackUrl": "https://oss.example.com/accompany.mp3",
      "zipUrl": "https://oss.example.com/result.zip"
    }
  }
}

期望输出：

分离完成了。
源文件名: song.mp3
taskId: task_xxx

人声：
https://oss.example.com/vocal.mp3

伴奏：
https://oss.example.com/accompany.mp3

打包下载：
https://oss.example.com/result.zip

示例 6：任务失败

已知接口返回：

{
  "success": true,
  "message": "操作成功",
  "data": {
    "taskId": "task_zzz",
    "status": "failed",
    "error": "任务处理失败: 接口未返回有效的任务ID"
  }
}

期望输出：

这次分离没有处理成功。
源文件名: song.mp3
taskId: task_zzz

原因：任务处理失败: 第三方接口未返回有效的任务ID

你可以稍后再试一次；如果还是失败，再检查一下音频文件本身是否有问题。

示例 7：接口直接返回错误

已知接口返回：

{
  "success": false,
  "message": "余额不足，请充值后重试",
  "code": "INSUFFICIENT_BALANCE"
}

期望输出：

现在还不能继续分离，因为当前账户余额不足。

你可以先去百音开放平台充值，处理好之后再重新提交这个音频。

如果你愿意，也可以等你充值完成后再让我继续帮你处理。

注意事项

1. 余额检查

在创建任务前，建议先确认账户余额是否充足：

• 人声伴奏分离：消耗较少积分

如果余额不足，接口会返回 INSUFFICIENT_BALANCE 错误。

2. 文件要求

• 音频文件 URL 需要公开可访问
• 支持格式：MP3, WAV, FLAC
• 建议文件大小不超过 100MB

3. 处理时间

处理时间受多种因素影响（文件大小、服务器负载等）：

4. 结果有效期

分离结果文件默认保留 7 天，请及时下载保存。

5. VIP 免费次数

VIP 用户享有每日免费次数：

• 可通过查询免费次数接口确认剩余次数
• 免费次数用尽后将扣除积分