ADD_MASKS API 接口文档

接口信息

POST /api/drafts/add_masks

功能描述

向现有草稿中的指定片段添加遮罩效果。遮罩是视频编辑中的重要功能，通过遮罩可以控制图像的可见区域，创造出各种视觉效果。支持多种遮罩类型（线性、镜面、圆形、矩形、爱心、星形），每种遮罩都可以精确配置位置、大小、羽化、旋转等属性。

请求参数

{
  "X": 100,
  "Y": 30,
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
  "feather": 22,
  "name": "线性",
  "rotation": 20,
  "segment_ids": [
    "1381ae8d-4acf-49af-b3cc-26e3c5ff648b"
  ],
  "width": 512,
  "height": 512,
  "invert": false,
  "roundCorner": 0
}

参数说明

参数名	类型	必填	默认值	说明
draft_url	string	✅	-	目标草稿的完整URL
segment_ids	array	✅	-	要应用遮罩的片段ID数组
name	string	❌	"线性"	遮罩类型名称
X	number	❌	0	遮罩中心X坐标（像素）
Y	number	❌	0	遮罩中心Y坐标（像素）
width	number	❌	512	遮罩宽度（像素）
height	number	❌	512	遮罩高度（像素）
feather	number	❌	0	羽化程度（0-100）
rotation	number	❌	0	旋转角度（度）
invert	boolean	❌	false	是否反转遮罩
roundCorner	number	❌	0	圆角半径（0-100）

支持的遮罩类型

遮罩名称	描述	适用场景
线性	线性渐变遮罩	线性过渡效果、渐变显示隐藏
镜面	镜像对称遮罩	对称效果、镜像反射
圆形	圆形遮罩	聚光灯效果、圆形裁剪
矩形	矩形遮罩	窗口效果、矩形裁剪
爱心	爱心形状遮罩	浪漫场景、特殊形状裁剪
星形	星形遮罩	闪光效果、装饰性裁剪

遮罩配置详解

位置控制: X、Y参数控制遮罩在画面中的位置
尺寸控制: width、height控制遮罩的大小
羽化效果: feather参数控制边缘的柔化程度，值越大边缘越柔和
旋转变换: rotation参数控制遮罩的旋转角度
反转效果: invert参数可以反转遮罩的显示/隐藏区域
圆角处理: roundCorner参数为矩形遮罩添加圆角效果

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "遮罩添加成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
    "masks_added": 2,
    "affected_segments": ["segment_001", "segment_002"],
    "mask_ids": ["mask_001", "mask_002"]
  }
}

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本线性遮罩

curl -X POST https://jy-api.fyshark.com/api/drafts/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["your-segment-id"],
    "name": "线性",
    "X": 100,
    "Y": 50,
    "feather": 20
  }'

2. 圆形聚光灯遮罩

curl -X POST https://jy-api.fyshark.com/api/drafts/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["your-segment-id"],
    "name": "圆形",
    "X": 200,
    "Y": 200,
    "width": 300,
    "height": 300,
    "feather": 50
  }'

3. 旋转矩形遮罩

curl -X POST https://jy-api.fyshark.com/api/drafts/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["your-segment-id"],
    "name": "矩形",
    "X": 150,
    "Y": 100,
    "width": 400,
    "height": 200,
    "rotation": 45,
    "roundCorner": 20
  }'

4. 反转爱心遮罩

curl -X POST https://jy-api.fyshark.com/api/drafts/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["your-segment-id"],
    "name": "爱心",
    "X": 300,
    "Y": 250,
    "width": 200,
    "height": 200,
    "invert": true,
    "feather": 30
  }'

5. 多片段应用遮罩

curl -X POST https://jy-api.fyshark.com/api/drafts/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["segment-id-1", "segment-id-2", "segment-id-3"],
    "name": "星形",
    "X": 200,
    "Y": 200,
    "width": 250,
    "height": 250,
    "rotation": 30
  }'

JavaScript 示例

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

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

// 使用示例 - 线性渐变遮罩
const linearMask = {
  segment_ids: ["your-segment-id"],
  name: "线性",
  X: 100,
  Y: 50,
  width: 600,
  height: 100,
  feather: 25,
  rotation: 0
};

// 使用示例 - 圆形聚光灯效果
const spotlightMask = {
  segment_ids: ["your-segment-id"],
  name: "圆形",
  X: 200,
  Y: 200,
  width: 300,
  height: 300,
  feather: 40,
  invert: false
};

// 使用示例 - 装饰性星形遮罩
const starMask = {
  segment_ids: ["your-segment-id"],
  name: "星形",
  X: 250,
  Y: 150,
  width: 200,
  height: 200,
  rotation: 15,
  feather: 20
};

try {
  const result = await addMasks(linearMask, draftUrl);
  console.log('遮罩添加成功:', result.data);
} catch (error) {
  console.error('添加失败:', error);
}

高级JavaScript示例

class MaskManager {
  constructor(baseUrl = 'https://jy-api.fyshark.com') {
    this.baseUrl = baseUrl;
  }

  async addMasks(draftUrl, maskConfig) {
    const response = await fetch(`${this.baseUrl}/api/drafts/add_masks`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        draft_url: draftUrl,
        ...maskConfig
      })
    });

    return response.json();
  }

  // 创建聚光灯效果
  createSpotlight(segmentIds, centerX, centerY, radius = 200, feather = 50) {
    return {
      segment_ids: segmentIds,
      name: "圆形",
      X: centerX,
      Y: centerY,
      width: radius,
      height: radius,
      feather: feather,
      invert: true // 反转使外部变暗
    };
  }

  // 创建窗口效果
  createWindow(segmentIds, x, y, width, height, cornerRadius = 0) {
    return {
      segment_ids: segmentIds,
      name: "矩形",
      X: x,
      Y: y,
      width: width,
      height: height,
      roundCorner: cornerRadius,
      feather: 10
    };
  }

  // 创建线性过渡
  createLinearTransition(segmentIds, x, y, width, height, angle = 0, feather = 30) {
    return {
      segment_ids: segmentIds,
      name: "线性",
      X: x,
      Y: y,
      width: width,
      height: height,
      rotation: angle,
      feather: feather
    };
  }

  // 创建装饰性形状遮罩
  createDecorative(segmentIds, shape, x, y, size = 150, rotation = 0) {
    const shapes = ["爱心", "星形"];
    const maskShape = shapes.includes(shape) ? shape : "星形";
    
    return {
      segment_ids: segmentIds,
      name: maskShape,
      X: x,
      Y: y,
      width: size,
      height: size,
      rotation: rotation,
      feather: 25
    };
  }

  // 创建镜面效果
  createMirror(segmentIds, x, y, width, height, angle = 0) {
    return {
      segment_ids: segmentIds,
      name: "镜面",
      X: x,
      Y: y,
      width: width,
      height: height,
      rotation: angle,
      feather: 15
    };
  }

  // 批量应用不同遮罩到不同片段
  async applyMultipleMasks(draftUrl, maskConfigs) {
    const results = [];
    
    for (const config of maskConfigs) {
      try {
        const result = await this.addMasks(draftUrl, config);
        results.push(result);
      } catch (error) {
        console.error('遮罩应用失败:', error);
        results.push({ error: error.message });
      }
    }
    
    return results;
  }
}

// 使用示例
const maskManager = new MaskManager();

// 创建聚光灯效果
const spotlight = maskManager.createSpotlight(
  ["segment-id"], 
  300, 300, 200, 60
);

// 创建窗口效果
const window = maskManager.createWindow(
  ["segment-id"], 
  100, 100, 400, 300, 20
);

// 创建装饰性星形
const star = maskManager.createDecorative(
  ["segment-id"], 
  "星形", 200, 150, 180, 30
);

// 批量应用
await maskManager.applyMultipleMasks(draftUrl, [spotlight, window, star]);

Python 示例 (可选)

import requests
import json

class MaskProcessor:
    def __init__(self, base_url="https://jy-api.fyshark.com"):
        self.base_url = base_url

    def add_masks(self, draft_url, mask_config):
        data = {
            "draft_url": draft_url,
            **mask_config
        }
        
        response = requests.post(
            f'{self.base_url}/api/drafts/add_masks',
            headers={'Content-Type': 'application/json'},
            json=data
        )
        return response.json()

    def create_circular_mask(self, segment_ids, center_x, center_y, radius, feather=30):
        return {
            "segment_ids": segment_ids,
            "name": "圆形",
            "X": center_x,
            "Y": center_y,
            "width": radius,
            "height": radius,
            "feather": feather
        }

    def create_linear_mask(self, segment_ids, x, y, width, height, angle=0, feather=25):
        return {
            "segment_ids": segment_ids,
            "name": "线性",
            "X": x,
            "Y": y,
            "width": width,
            "height": height,
            "rotation": angle,
            "feather": feather
        }

# 使用示例
processor = MaskProcessor()

# 创建圆形遮罩
circular_mask = processor.create_circular_mask(
    ["your-segment-id"], 200, 200, 150, 40
)

result = processor.add_masks("YOUR_DRAFT_URL", circular_mask)
print(f"结果: {result}")

错误码说明

错误码	错误信息	说明	解决方案
400	draft_url是必填项	缺少草稿URL参数	提供有效的草稿URL
400	segment_ids是必填项	缺少片段ID数组	提供要应用遮罩的片段ID数组
400	segment_ids必须是数组	segment_ids参数格式错误	确保segment_ids是数组格式
400	遮罩参数验证失败	遮罩配置参数不符合要求	检查遮罩类型和参数范围
400	不支持的遮罩类型	name参数不在支持列表中	使用支持的遮罩类型之一
404	草稿不存在	指定的草稿URL无效	检查草稿URL是否正确
404	片段不存在	指定的segment_id无效	检查片段ID是否正确
500	遮罩处理失败	内部处理错误	联系技术支持

注意事项

遮罩类型: 只支持6种预定义的遮罩类型，无效类型会自动使用"线性"
坐标系统: X、Y坐标以像素为单位，原点在左上角
参数范围: feather和roundCorner参数范围为0-100
片段兼容性: 只能对视频类型的片段应用遮罩
性能考虑: 复杂遮罩可能影响渲染性能
多片段: 可以对多个片段应用相同的遮罩配置

工作流程

验证必填参数（draft_url, segment_ids）
验证遮罩类型和配置参数
获取并解密草稿内容
遍历片段ID数组，逐个处理：
- 根据segment_id获取目标片段
- 获取片段关联的素材信息（宽高）
- 根据遮罩类型设置resource_id和resource_type
- 创建遮罩配置对象
- 计算相对坐标和尺寸
- 添加遮罩到草稿materials.masks数组
- 将遮罩ID添加到片段的extra_material_refs
加密并保存更新后的草稿
返回处理结果统计

技术特性

遮罩类型系统

线性遮罩: 适用于线性过渡效果
镜面遮罩: 创造对称镜像效果
几何遮罩: 圆形、矩形基础形状
装饰遮罩: 爱心、星形特殊形状

配置系统

位置控制: 精确的X、Y坐标定位
尺寸调节: 独立的宽度和高度控制
边缘处理: 羽化效果创造柔和边缘
变换支持: 旋转和反转功能
圆角支持: 矩形遮罩的圆角处理

自适应计算

坐标归一化: 自动将像素坐标转换为相对坐标
尺寸适配: 根据素材尺寸自动调整遮罩大小
比例保持: 保持遮罩的宽高比

最佳实践

遮罩选择建议

const maskUseCases = {
  // 聚光灯效果
  spotlight: {
    name: "圆形",
    invert: true,
    feather: 50
  },
  
  // 窗口效果
  window: {
    name: "矩形",
    roundCorner: 15,
    feather: 20
  },
  
  // 线性过渡
  transition: {
    name: "线性",
    rotation: 90,
    feather: 30
  },
  
  // 装饰效果
  decoration: {
    name: "星形",
    rotation: 15,
    feather: 25
  }
};

参数配置指南

羽化设置:
- 硬边缘: feather = 0-10
- 柔和边缘: feather = 20-40
- 超柔和: feather = 50-80
尺寸建议:
- 小型装饰: 100-200px
- 中型效果: 300-500px
- 大型覆盖: 600px以上
旋转角度:
- 水平线性: 0°
- 垂直线性: 90°
- 对角线性: 45°或135°

性能优化

遮罩数量: 建议单个片段不超过3个遮罩
羽化程度: 过高的羽化值可能影响性能
尺寸控制: 避免超大尺寸的遮罩
批量应用: 相同配置的遮罩可以批量应用到多个片段

高级用法

动态遮罩效果

虽然本接口创建静态遮罩，但可以结合关键帧动画实现动态效果：

// 先添加遮罩
await addMasks(maskConfig, draftUrl);

// 再对遮罩应用关键帧动画
const maskKeyframes = [
  {
    segment_id: "your-segment-id",
    property: "KFTypePositionX",
    offset: 0,
    value: -0.5
  },
  {
    segment_id: "your-segment-id",
    property: "KFTypePositionX",
    offset: 1,
    value: 0.5
  }
];

await addKeyframes(maskKeyframes, draftUrl);

组合遮罩效果

const createComplexMask = async (segmentId, draftUrl) => {
  // 基础圆形遮罩
  const baseMask = {
    segment_ids: [segmentId],
    name: "圆形",
    X: 200,
    Y: 200,
    width: 300,
    height: 300,
    feather: 30
  };
  
  // 装饰星形遮罩
  const decorMask = {
    segment_ids: [segmentId],
    name: "星形",
    X: 200,
    Y: 200,
    width: 100,
    height: 100,
    feather: 20
  };
  
  // 依次应用
  await addMasks(baseMask, draftUrl);
  await addMasks(decorMask, draftUrl);
};

更新日志

v1.0.0 (2025-08-01): 初始版本发布
- 支持6种基础遮罩类型
- 实现完整的遮罩配置系统
- 支持多片段批量应用
- 完善的参数验证机制
- 自适应坐标和尺寸计算

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

ADD_MASKS API 接口文档

ADD_MASKS API 接口文档

接口信息

功能描述

请求参数

参数说明

支持的遮罩类型

遮罩配置详解

响应格式

成功响应 (200)

错误响应 (4xx/5xx)

使用示例

cURL 示例

1. 基本线性遮罩

2. 圆形聚光灯遮罩

3. 旋转矩形遮罩

4. 反转爱心遮罩

5. 多片段应用遮罩

JavaScript 示例

高级JavaScript示例

Python 示例 (可选)

错误码说明

注意事项

工作流程

技术特性

遮罩类型系统

配置系统

自适应计算

最佳实践

遮罩选择建议

参数配置指南

性能优化

高级用法

动态遮罩效果

组合遮罩效果

相关接口

更新日志