ADD_EFFECTS API 接口文档

📄 API_ADD_EFFECTS.md 🕒 8/10/2025, 6:48:23 PM 📏 6KB

ADD_EFFECTS API 接口文档

接口信息

POST /api/drafts/add_effects

功能描述

向现有草稿中添加视频特效轨道和特效片段。支持批量添加多种视频特效，包括边框特效、滤镜特效、动态特效等，为视频内容增加丰富的视觉效果。

请求参数

{
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/xxx.json",
  "effect_infos": "[{\"effect_title\":\"录制边框 III\",\"end\":5000000,\"start\":0}]"
}

参数说明

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

effect_infos 数组元素说明

参数名 类型 必填 默认值 说明
effect_title string ✅ - 特效名称/标题
start number ✅ - 特效开始时间（微秒）
end number ✅ - 特效结束时间（微秒）

常见特效名称

特效类型 特效名称示例
边框特效 "录制边框 III", "简约边框", "霓虹边框"
滤镜特效 "复古滤镜", "黑白滤镜", "暖色调"
动态特效 "粒子效果", "光晕效果", "闪烁特效"
转场特效 "淡入淡出", "推拉门", "马赛克转场"

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "特效添加成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
    "track_id": "effect_track_123",
    "effect_ids": ["effect_001", "effect_002"],
    "segment_ids": ["seg_001", "seg_002"]
  }
}

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

curl -X POST https://jy-api.fyshark.com/api/drafts/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/xxx.json",
    "effect_infos": "[{\"effect_title\":\"录制边框 III\",\"end\":5000000,\"start\":0}]"
  }'

JavaScript 示例

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

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

// 使用示例
const effects = [
  {
    effect_title: "录制边框 III",
    start: 0,
    end: 5000000
  },
  {
    effect_title: "复古滤镜",
    start: 2000000,
    end: 8000000
  }
];

try {
  const result = await addEffects(effects, draftUrl);
  console.log('特效添加成功:', result.data);
} catch (error) {
  console.error('添加失败:', error);
}

Python 示例 (可选)

import requests
import json

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

# 使用示例
effects = [
    {
        "effect_title": "录制边框 III",
        "start": 0,
        "end": 5000000
    }
]

result = add_effects(effects, draft_url)
print(result)

错误码说明

错误码 错误信息 说明 解决方案
400 draft_url是必填项 缺少草稿URL参数 提供有效的草稿URL
400 effect_infos是必填项 缺少特效信息参数 提供特效信息数组
400 effect_infos格式错误 JSON解析失败 检查JSON格式是否正确
400 特效信息验证失败 特效数据不符合要求 检查特效名称和时间范围
404 草稿不存在 指定的草稿URL无效 检查草稿URL是否正确
404 特效不存在 指定的特效名称不存在 检查特效名称是否正确
500 特效处理失败 内部处理错误 联系技术支持

注意事项

  1. effect_infos参数格式: 必须是JSON字符串格式，不是直接的数组对象
  2. 时间单位: 所有时间参数（start, end）都使用微秒为单位
  3. 特效名称: 特效名称必须与系统中存在的特效完全匹配
  4. 时间范围: 确保start < end，且时间范围合理
  5. 特效叠加: 多个特效可以在同一时间段内叠加使用
  6. 性能影响: 过多的特效可能影响视频渲染性能

工作流程

  1. 验证必填参数（draft_url, effect_infos）
  2. 解析effect_infos JSON字符串
  3. 验证特效信息格式
  4. 获取并解密草稿内容
  5. 创建新的特效轨道
  6. 遍历特效信息数组，逐个处理：
    • 根据特效名称创建特效素材
    • 验证特效是否存在
    • 添加特效片段到轨道
    • 设置特效时间范围
  7. 加密并保存更新后的草稿
  8. 返回轨道ID和特效ID列表

特效类型详解

边框特效

为视频添加各种样式的边框装饰：

{
  "effect_title": "录制边框 III",
  "start": 0,
  "end": 10000000
}

滤镜特效

改变视频的色彩和风格：

{
  "effect_title": "复古滤镜",
  "start": 0,
  "end": 15000000
}

动态特效

添加动态的视觉元素：

{
  "effect_title": "粒子效果",
  "start": 5000000,
  "end": 20000000
}

高级用法

特效时间重叠

多个特效可以在同一时间段内同时生效：

[
  {
    "effect_title": "录制边框 III",
    "start": 0,
    "end": 10000000
  },
  {
    "effect_title": "复古滤镜",
    "start": 5000000,
    "end": 15000000
  }
]

特效序列

创建特效序列，实现连续的视觉效果：

[
  {
    "effect_title": "淡入效果",
    "start": 0,
    "end": 2000000
  },
  {
    "effect_title": "主要特效",
    "start": 2000000,
    "end": 18000000
  },
  {
    "effect_title": "淡出效果",
    "start": 18000000,
    "end": 20000000
  }
]

错误排查

常见问题

  1. 问题: 特效不存在错误
    解决: 确认特效名称拼写正确，检查系统支持的特效列表

  2. 问题: 时间范围错误
    解决: 确保start < end，且时间值为正数

  3. 问题: JSON解析失败
    解决: 检查effect_infos是否为有效的JSON字符串格式

调试建议

性能优化建议

  1. 合理使用特效数量: 避免同时使用过多特效
  2. 优化时间范围: 特效时间范围不宜过长
  3. 测试渲染性能: 在实际使用前测试特效组合的渲染性能

更新日志

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

📚 文档中心 🏠 API首页
↑