ADD_CAPTIONS API 接口文档

接口信息

POST /api/drafts/add_captions

功能描述

向现有草稿中添加字幕轨道和字幕片段。支持丰富的字幕样式设置，包括关键词高亮、字体样式、边框效果、对齐方式、透明度和动画效果等。

请求参数

{
  "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15,\"font_size\":15}]",
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
  "text_color": "#ff1837",
  "border_color": "#fe8a80",
  "alignment": 2,
  "alpha": 0.5
}

参数说明

captions 数组元素说明

对齐方式说明

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "字幕添加成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=...",
    "track_id": "text_track_123",
    "text_ids": ["text_001", "text_002"],
    "segment_ids": ["seg_001", "seg_002"],
    "segment_infos": [
      {
        "id": "seg_001",
        "start": 0,
        "end": 10000000
      }
    ]
  }
}

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

curl -X POST https://jy-api.fyshark.com/api/drafts/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15,\"font_size\":15}]",
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/xxx.json",
    "text_color": "#ff1837",
    "border_color": "#fe8a80",
    "alignment": 2,
    "alpha": 0.5
  }'

JavaScript 示例

const addCaptions = async (captionsData, draftUrl, options = {}) => {
  const response = await fetch('/api/drafts/add_captions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      captions: JSON.stringify(captionsData),
      draft_url: draftUrl,
      text_color: options.textColor || "#ffffff",
      border_color: options.borderColor,
      alignment: options.alignment || 1,
      alpha: options.alpha || 1.0,
      font: options.font,
      font_size: options.fontSize || 15
    })
  });

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

// 使用示例
const captions = [
  {
    start: 0,
    end: 10000000,
    text: "你好，剪映",
    keyword: "好",
    keyword_color: "#457616",
    keyword_font_size: 15,
    font_size: 15
  },
  {
    start: 10000000,
    end: 20000000,
    text: "欢迎使用字幕功能",
    keyword: "字幕",
    keyword_color: "#ff0000",
    in_animation: "fade_in",
    out_animation: "fade_out"
  }
];

const options = {
  textColor: "#ff1837",
  borderColor: "#fe8a80", 
  alignment: 2,
  alpha: 0.8
};

try {
  const result = await addCaptions(captions, draftUrl, options);
  console.log('字幕添加成功:', result.data);
} catch (error) {
  console.error('添加失败:', error);
}

Python 示例 (可选)

import requests
import json

def add_captions(captions_data, draft_url, **options):
    response = requests.post('https://jy-api.fyshark.com/api/drafts/add_captions', 
        headers={'Content-Type': 'application/json'},
        json={
            'captions': json.dumps(captions_data),
            'draft_url': draft_url,
            'text_color': options.get('text_color', '#ffffff'),
            'border_color': options.get('border_color'),
            'alignment': options.get('alignment', 1),
            'alpha': options.get('alpha', 1.0),
            'font': options.get('font'),
            'font_size': options.get('font_size', 15)
        }
    )
    return response.json()

# 使用示例
captions = [
    {
        "start": 0,
        "end": 10000000,
        "text": "你好，剪映",
        "keyword": "好",
        "keyword_color": "#457616",
        "keyword_font_size": 15,
        "font_size": 15
    }
]

result = add_captions(captions, draft_url, 
    text_color="#ff1837",
    border_color="#fe8a80",
    alignment=2,
    alpha=0.5
)
print(result)

错误码说明

注意事项

1. captions参数格式: 必须是JSON字符串格式，不是直接的数组对象
2. 时间单位: 所有时间参数（start, end）都使用微秒为单位
3. 颜色格式: 所有颜色参数使用十六进制格式（如 #ffffff）
4. 关键词分隔: 多个关键词使用竖线|分隔
5. 对齐方式: alignment参数范围为0-5，超出范围将使用默认值1
6. 透明度范围: alpha参数范围为0.0-1.0，0为完全透明，1为完全不透明
7. 字体支持: font参数需要草稿中存在对应的字体资源

工作流程

1. 验证必填参数（draft_url, captions）
2. 解析captions JSON字符串
3. 验证字幕信息格式
4. 获取并解密草稿内容
5. 创建新的文本轨道
6. 遍历字幕信息数组，逐个处理：
   • 创建字幕素材
   • 设置文本样式（颜色、字体、大小等）
   • 处理关键词高亮
   • 设置边框效果
   • 应用动画效果
   • 添加字幕片段到轨道
7. 加密并保存更新后的草稿
8. 返回轨道ID和字幕ID列表

高级功能

关键词高亮

支持在字幕文本中高亮显示特定关键词：

{
  "text": "你好，剪映",
  "keyword": "好|剪映",
  "keyword_color": "#ff0000",
  "keyword_font_size": 18
}

动画效果

支持入场、出场和循环动画：

{
  "in_animation": "fade_in",
  "out_animation": "fade_out", 
  "loop_animation": "bounce",
  "in_animation_duration": 1000000,
  "out_animation_duration": 1000000,
  "loop_animation_duration": 2000000
}

文本变换

支持缩放和位置调整：

{
  "scale_x": 1.2,
  "scale_y": 1.0,
  "transform_x": 100,
  "transform_y": 50
}

错误排查

常见问题

1. 问题: JSON解析失败
   解决: 确保captions是正确的JSON字符串格式，特别注意转义字符

2. 问题: 字幕显示位置不正确
   解决: 检查alignment参数值，确保在0-5范围内

3. 问题: 关键词高亮不生效
   解决: 确保keyword存在于text中，检查keyword_color格式

调试建议

• 使用简单的字幕文本进行初步测试
• 验证时间参数的逻辑关系（start < end）
• 检查颜色值格式是否为有效的十六进制

更新日志

• v1.0.0 (2025-08-01): 初始版本
  • 实现基础字幕添加功能
  • 支持关键词高亮
  • 支持丰富的文本样式
  • 支持动画效果
  • 支持文本变换
  • 完善错误处理机制

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