ADD_STICKER API 接口文档

接口信息

POST /api/drafts/add_sticker

功能描述

向现有草稿中添加贴纸素材。贴纸是视频编辑中常用的装饰元素，通过贴纸可以为视频添加各种有趣的视觉效果和装饰。支持贴纸的位置调整、缩放变换和时间范围控制，让您能够精确控制贴纸在视频中的显示效果。

请求参数

{
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-03-09/draft/10fa8174-0fc8-4fc9-a3d8-f52765b4ae0c.json",
  "sticker_id": "7326810673609018675",
  "start": 0,
  "end": 5000000,
  "scale": 2,
  "transform_x": 500,
  "transform_y": 900
}

参数说明

参数名	类型	必填	默认值	说明
draft_url	string	✅	-	目标草稿的完整URL
sticker_id	string	✅	-	贴纸的唯一标识ID
start	number	✅	-	贴纸开始时间（微秒）
end	number	✅	-	贴纸结束时间（微秒）
scale	number	❌	1.0	贴纸缩放比例
transform_x	number	❌	0	X轴位置偏移（像素）
transform_y	number	❌	0	Y轴位置偏移（像素）

参数详解

时间参数

• start: 贴纸在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
• end: 贴纸在时间轴上的结束时间，单位为微秒
• duration: 贴纸显示时长 = end - start

缩放参数

• scale: 贴纸的缩放比例
  • 1.0 = 原始大小
  • 0.5 = 缩小到一半
  • 2.0 = 放大到两倍
  • 建议范围：0.1 - 5.0

位置参数

• transform_x: 贴纸在X轴方向的位置偏移，单位为像素
  • 正值向右移动
  • 负值向左移动
  • 以画布中心为原点
• transform_y: 贴纸在Y轴方向的位置偏移，单位为像素
  • 正值向下移动
  • 负值向上移动
  • 以画布中心为原点

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "贴纸添加成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
    "sticker_id": "7326810673609018675",
    "track_id": "track-uuid",
    "segment_id": "segment-uuid",
    "duration": 5000000
  }
}

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本贴纸添加

curl -X POST https://jy-api.fyshark.com/api/drafts/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 0,
    "end": 5000000
  }'

2. 带缩放的贴纸

curl -X POST https://jy-api.fyshark.com/api/drafts/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 1000000,
    "end": 6000000,
    "scale": 1.5
  }'

3. 位置调整的贴纸

curl -X POST https://jy-api.fyshark.com/api/drafts/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 2000000,
    "end": 7000000,
    "transform_x": 300,
    "transform_y": -200
  }'

4. 完整配置的贴纸

curl -X POST https://jy-api.fyshark.com/api/drafts/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 0,
    "end": 5000000,
    "scale": 2,
    "transform_x": 500,
    "transform_y": 900
  }'

JavaScript 示例

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

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

// 使用示例 - 基本贴纸
const basicSticker = {
  sticker_id: "7326810673609018675",
  start: 0,
  end: 5000000  // 显示5秒
};

// 使用示例 - 放大的贴纸
const scaledSticker = {
  sticker_id: "7326810673609018675",
  start: 1000000,  // 1秒后开始
  end: 6000000,    // 显示5秒
  scale: 1.8       // 放大1.8倍
};

// 使用示例 - 定位的贴纸
const positionedSticker = {
  sticker_id: "7326810673609018675",
  start: 2000000,
  end: 8000000,
  scale: 1.2,
  transform_x: 400,  // 向右移动400像素
  transform_y: -300  // 向上移动300像素
};

try {
  const result = await addSticker(basicSticker, draftUrl);
  console.log('贴纸添加成功:', result.data);
} catch (error) {
  console.error('添加失败:', error);
}

高级JavaScript示例

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

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

    return response.json();
  }

  // 创建定时贴纸（在指定时间显示）
  createTimedSticker(stickerId, startSeconds, durationSeconds, options = {}) {
    const startMicros = startSeconds * 1000000;
    const endMicros = startMicros + (durationSeconds * 1000000);
    
    return {
      sticker_id: stickerId,
      start: startMicros,
      end: endMicros,
      scale: options.scale || 1.0,
      transform_x: options.transform_x || 0,
      transform_y: options.transform_y || 0
    };
  }

  // 创建角落贴纸
  createCornerSticker(stickerId, corner, startSeconds, durationSeconds, scale = 0.8) {
    const positions = {
      'top-left': { transform_x: -400, transform_y: -300 },
      'top-right': { transform_x: 400, transform_y: -300 },
      'bottom-left': { transform_x: -400, transform_y: 300 },
      'bottom-right': { transform_x: 400, transform_y: 300 }
    };

    const position = positions[corner] || positions['top-right'];
    
    return this.createTimedSticker(stickerId, startSeconds, durationSeconds, {
      scale: scale,
      ...position
    });
  }

  // 创建中心贴纸
  createCenterSticker(stickerId, startSeconds, durationSeconds, scale = 1.5) {
    return this.createTimedSticker(stickerId, startSeconds, durationSeconds, {
      scale: scale,
      transform_x: 0,
      transform_y: 0
    });
  }

  // 批量添加贴纸序列
  async addStickerSequence(draftUrl, stickerSequence) {
    const results = [];
    
    for (const stickerConfig of stickerSequence) {
      try {
        const result = await this.addSticker(draftUrl, stickerConfig);
        results.push(result);
        
        // 添加延迟避免请求过快
        await new Promise(resolve => setTimeout(resolve, 100));
      } catch (error) {
        console.error('贴纸添加失败:', error);
        results.push({ error: error.message });
      }
    }
    
    return results;
  }

  // 创建动画序列（多个相同贴纸依次出现）
  createAnimationSequence(stickerId, positions, intervalSeconds = 1, durationSeconds = 2) {
    const sequence = [];
    
    positions.forEach((pos, index) => {
      const startTime = index * intervalSeconds;
      sequence.push(this.createTimedSticker(
        stickerId, 
        startTime, 
        durationSeconds,
        pos
      ));
    });
    
    return sequence;
  }
}

// 使用示例
const stickerManager = new StickerManager();

// 创建角落贴纸
const cornerSticker = stickerManager.createCornerSticker(
  "7326810673609018675", 
  "top-right", 
  2, 
  5
);

// 创建中心贴纸
const centerSticker = stickerManager.createCenterSticker(
  "7326810673609018675", 
  0, 
  3, 
  2.0
);

// 创建动画序列
const animationPositions = [
  { transform_x: -300, transform_y: 0, scale: 1.0 },
  { transform_x: 0, transform_y: 0, scale: 1.5 },
  { transform_x: 300, transform_y: 0, scale: 1.0 }
];

const sequence = stickerManager.createAnimationSequence(
  "7326810673609018675",
  animationPositions,
  1,  // 间隔1秒
  2   // 每个显示2秒
);

// 批量添加
await stickerManager.addStickerSequence(draftUrl, sequence);

Python 示例 (可选)

import requests
import json

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

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

    def create_timed_sticker(self, sticker_id, start_seconds, duration_seconds, **options):
        start_micros = start_seconds * 1000000
        end_micros = start_micros + (duration_seconds * 1000000)
        
        config = {
            "sticker_id": sticker_id,
            "start": start_micros,
            "end": end_micros
        }
        
        # 添加可选参数
        if "scale" in options:
            config["scale"] = options["scale"]
        if "transform_x" in options:
            config["transform_x"] = options["transform_x"]  
        if "transform_y" in options:
            config["transform_y"] = options["transform_y"]
            
        return config

    def create_corner_sticker(self, sticker_id, corner, start_seconds, duration_seconds, scale=0.8):
        positions = {
            'top-left': {'transform_x': -400, 'transform_y': -300},
            'top-right': {'transform_x': 400, 'transform_y': -300},
            'bottom-left': {'transform_x': -400, 'transform_y': 300},
            'bottom-right': {'transform_x': 400, 'transform_y': 300}
        }
        
        position = positions.get(corner, positions['top-right'])
        
        return self.create_timed_sticker(
            sticker_id, 
            start_seconds, 
            duration_seconds,
            scale=scale,
            **position
        )

# 使用示例
processor = StickerProcessor()

# 创建角落贴纸
corner_sticker = processor.create_corner_sticker(
    "7326810673609018675", 
    "top-right", 
    2, 
    5
)

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

错误码说明

错误码	错误信息	说明	解决方案
400	draft_url是必填项	缺少草稿URL参数	提供有效的草稿URL
400	sticker_id是必填项	缺少贴纸ID参数	提供有效的贴纸ID
400	start是必填项	缺少开始时间参数	提供开始时间（微秒）
400	end是必填项	缺少结束时间参数	提供结束时间（微秒）
400	贴纸配置验证失败	贴纸参数不符合要求	检查参数类型和数值范围
400	时间范围无效	end必须大于start	确保结束时间大于开始时间
400	缩放值无效	scale必须为正数	使用大于0的缩放值
404	草稿不存在	指定的草稿URL无效	检查草稿URL是否正确
404	贴纸不存在	指定的sticker_id无效	检查贴纸ID是否正确
500	贴纸处理失败	内部处理错误	联系技术支持

注意事项

1. 时间单位: start和end参数使用微秒作为单位（1秒 = 1,000,000微秒）
2. 时间范围: end必须大于start，否则会报错
3. 坐标系统: transform_x和transform_y以画布中心为原点
4. 缩放范围: 建议scale值在0.1-5.0之间，避免过小或过大
5. 贴纸ID: sticker_id必须是有效的贴纸资源ID
6. 性能考虑: 大量贴纸可能影响渲染性能

工作流程

1. 验证必填参数（draft_url, sticker_id, start, end）
2. 验证贴纸配置参数
3. 获取并解密草稿内容
4. 创建贴纸素材（使用sticker_id）
5. 添加贴纸轨道到草稿
6. 创建贴纸片段，设置时间范围
7. 应用缩放和位置变换
8. 加密并保存更新后的草稿
9. 返回处理结果

技术特性

贴纸系统

• 素材创建: 基于sticker_id创建贴纸素材
• 轨道管理: 自动创建STICKER类型轨道
• 片段控制: 精确的时间范围控制
• 变换支持: 缩放和位置变换

坐标系统

• 相对坐标: 自动将像素坐标转换为相对坐标
• 中心原点: 以画布中心为坐标原点
• 自适应: 根据画布尺寸自动调整坐标

最佳实践

贴纸使用建议

const stickerBestPractices = {
  // 时间设置
  timing: {
    minDuration: 1000000,    // 最短1秒
    maxDuration: 30000000,   // 最长30秒
    recommended: 5000000     // 推荐5秒
  },
  
  // 缩放设置
  scaling: {
    small: 0.5,      // 小贴纸
    normal: 1.0,     // 正常大小
    large: 1.5,      // 大贴纸
    emphasis: 2.0    // 强调效果
  },
  
  // 位置设置
  positions: {
    center: { transform_x: 0, transform_y: 0 },
    topLeft: { transform_x: -400, transform_y: -300 },
    topRight: { transform_x: 400, transform_y: -300 },
    bottomLeft: { transform_x: -400, transform_y: 300 },
    bottomRight: { transform_x: 400, transform_y: 300 }
  }
};

性能优化

1. 贴纸数量: 建议单个视频不超过10个贴纸
2. 时间分布: 避免过多贴纸同时显示
3. 尺寸控制: 避免过大的缩放值
4. 位置合理: 确保贴纸在画布范围内

创意应用

1. 装饰效果: 在视频角落添加小贴纸
2. 强调内容: 在关键时刻添加大贴纸
3. 动画序列: 多个贴纸依次出现
4. 主题装饰: 根据视频主题选择贴纸

高级用法

动态贴纸效果

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

// 先添加贴纸
await addSticker(stickerConfig, draftUrl);

// 再对贴纸应用关键帧动画
const stickerKeyframes = [
  {
    segment_id: "sticker-segment-id",
    property: "KFTypeScaleX",
    offset: 0,
    value: 0.5
  },
  {
    segment_id: "sticker-segment-id",
    property: "KFTypeScaleX",
    offset: 1,
    value: 2.0
  }
];

await addKeyframes(stickerKeyframes, draftUrl);

贴纸组合效果

const createStickerCombo = async (draftUrl, baseStickerId) => {
  // 背景装饰贴纸
  const backgroundSticker = {
    sticker_id: baseStickerId,
    start: 0,
    end: 10000000,
    scale: 0.8,
    transform_x: -300,
    transform_y: 200
  };
  
  // 主要贴纸
  const mainSticker = {
    sticker_id: baseStickerId,
    start: 2000000,
    end: 8000000,
    scale: 2.0,
    transform_x: 0,
    transform_y: 0
  };
  
  // 强调贴纸
  const emphasisSticker = {
    sticker_id: baseStickerId,
    start: 5000000,
    end: 7000000,
    scale: 1.2,
    transform_x: 300,
    transform_y: -150
  };
  
  // 依次添加
  await addSticker(backgroundSticker, draftUrl);
  await addSticker(mainSticker, draftUrl);
  await addSticker(emphasisSticker, draftUrl);
};

相关接口

• CREATE_DRAFT - 创建新草稿
• ADD_IMAGES - 批量添加图片
• ADD_KEYFRAMES - 批量添加关键帧（可用于贴纸动画）
• ADD_EFFECTS - 批量添加特效
• ADD_MASKS - 批量添加遮罩

更新日志

• v1.0.0 (2025-08-01): 初始版本发布
  • 支持基础贴纸添加功能
  • 实现贴纸位置和缩放控制
  • 支持精确的时间范围设置
  • 完善的参数验证机制
  • 自适应坐标系统

---

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