ADD_AUDIOS API 接口文档

接口信息

POST /api/drafts/add_audios

功能描述

向现有草稿中批量添加音频轨道和音频片段。支持多个音频文件的同时添加，每个音频可以设置不同的时间范围、音量和音效。

请求参数

{
  "audio_infos": "[{\"audio_url\":\"https://example.com/audio.mp3\",\"duration\":23184000,\"end\":23184000,\"start\":0,\"volume\":1.0,\"audio_effect\":\"reverb\"}]",
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-02-24/draft/xxx.json"
}

参数说明

参数名	类型	必填	默认值	说明
audio_infos	string	✅	-	JSON字符串格式的音频信息数组
draft_url	string	✅	-	目标草稿的完整URL

audio_infos 数组元素说明

参数名	类型	必填	默认值	说明
audio_url	string	✅	-	音频文件URL
duration	number	✅	-	音频总时长（微秒）
start	number	✅	-	音频片段开始时间（微秒）
end	number	✅	-	音频片段结束时间（微秒）
volume	number	否	1.0	音频音量（0.0-2.0）
audio_effect	string	否	-	音频效果名称

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "音频添加成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
    "track_id": "audio_track_123",
    "audio_ids": ["audio_001", "audio_002"]
  }
}

错误响应 (4xx/5xx)

{
  "status": "error",
  "message": "错误信息",
  "error": "详细错误描述"
}

使用示例

cURL 示例

curl -X POST https://jy-api.fyshark.com/api/drafts/add_audios \
  -H "Content-Type: application/json" \
  -d '{
    "audio_infos": "[{\"audio_url\":\"https://lf-bot-studio-plugin-resource.coze.cn/obj/bot-studio-platform-plugin-tos/sami/tts/fe9baa8f474e4a20a293b7228707ff9c.mp3\",\"duration\":23184000,\"end\":23184000,\"start\":0,\"volume\":1.0}]",
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/xxx.json"
  }'

JavaScript 示例

const addAudios = async (audioInfos, draftUrl) => {
  const response = await fetch('/api/drafts/add_audios', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      audio_infos: JSON.stringify(audioInfos),
      draft_url: draftUrl
    })
  });

  const result = await response.json();
  return result;
};

// 使用示例
const audioInfos = [
  {
    audio_url: "https://example.com/audio1.mp3",
    duration: 23184000,
    start: 0,
    end: 23184000,
    volume: 1.0
  },
  {
    audio_url: "https://example.com/audio2.mp3", 
    duration: 15000000,
    start: 5000000,
    end: 20000000,
    volume: 0.8,
    audio_effect: "reverb"
  }
];

addAudios(audioInfos, draftUrl).then(result => {
  console.log('音频添加结果:', result);
});

Python 示例 (可选)

import requests
import json

def add_audios(audio_infos, draft_url):
    response = requests.post('https://jy-api.fyshark.com/api/drafts/add_audios', 
        headers={'Content-Type': 'application/json'},
        json={
            'audio_infos': json.dumps(audio_infos),
            'draft_url': draft_url
        }
    )
    return response.json()

# 使用示例
audio_infos = [
    {
        "audio_url": "https://example.com/audio.mp3",
        "duration": 23184000,
        "start": 0,
        "end": 23184000,
        "volume": 1.0
    }
]

result = add_audios(audio_infos, draft_url)
print(result)

错误码说明

错误码	错误信息	说明	解决方案
400	draft_url是必填项	缺少草稿URL参数	提供有效的草稿URL
400	audio_infos是必填项	缺少音频信息参数	提供音频信息数组
400	audio_infos格式错误	JSON解析失败	检查JSON格式是否正确
404	草稿不存在	指定的草稿URL无效	检查草稿URL是否正确
500	草稿处理失败	内部处理错误	联系技术支持

注意事项

audio_infos参数格式: 必须是JSON字符串格式，不是直接的数组对象
时间单位: 所有时间参数（duration, start, end）都使用微秒为单位
音量范围: volume参数范围为0.0-2.0，1.0为正常音量
音频效果: audio_effect为可选参数，支持的效果类型依赖于jy_draft包
并发处理: 支持在同一次请求中添加多个音频片段

工作流程

验证必填参数（draft_url, audio_infos）
解析audio_infos JSON字符串
获取并解密草稿内容
创建新的音频轨道
遍历音频信息数组，逐个处理：
- 创建音频素材
- 添加音频片段到轨道
- 应用音效（如果指定）
- 设置音量（如果指定）
加密并保存更新后的草稿
返回轨道ID和音频ID列表

错误排查

常见问题

问题: JSON解析失败
解决: 确保audio_infos是正确的JSON字符串格式，特别注意转义字符
问题: 音频文件无法访问
解决: 检查音频URL是否可正常访问，确认网络连接
问题: 时间参数错误
解决: 确保start < end，且都在duration范围内

调试建议

使用较小的音频文件进行初步测试
验证时间参数的逻辑关系
检查草稿URL的有效性

更新日志

v1.0.0 (2025-08-01): 初始版本
- 实现批量音频添加功能
- 支持音量和音效设置
- 完善错误处理机制

📖 文档版本: v1.0.0
🔄 最后更新: 2025-08-01
👤 维护者: Developer