【剪映小助手源码精讲】第25章贴纸添加服务

最新推荐文章于 2026-01-10 13:11:27 发布

原创最新推荐文章于 2026-01-10 13:11:27 发布 · 433 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#AIGC #python

第25章贴纸添加服务

25.1 概述

贴纸添加服务是剪映小助手的核心功能之一，主要负责在视频编辑草稿中添加各种类型的贴纸元素。该服务通过调用剪映API，将贴纸作为独立的轨道添加到草稿中，支持自定义贴纸的位置、大小、显示时间等属性。

25.2 核心实现

25.2.1 服务入口函数

贴纸添加服务的核心实现位于 src/service/add_sticker.py 文件中，主要入口函数为 add_sticker()：

async def add_sticker(request: AddStickerRequest) -> AddStickerResponse:
    """添加贴纸到草稿"""
    logger.info(f"添加贴纸到草稿: {request.draft_url}")
    
    # 参数验证
    if not request.draft_url or not request.sticker_id:
        raise ValueError("草稿URL和贴纸ID不能为空")
    
    # 获取草稿缓存
    draft = await get_draft_cache(request.draft_url)
    if not draft:
        raise INVALID_DRAFT_URL
    
    # 创建贴纸轨道
    sticker_track = draft.create_track("sticker")
    
    # 创建贴纸片段
    sticker_segment = create_sticker_segment(request, draft)
    
    # 添加贴纸到轨道
    sticker_track.add_segment(sticker_segment)
    
    # 保存草稿
    await save_draft_cache(request.draft_url, draft)
    
    return AddStickerResponse(
        draft_url=request.draft_url,
        sticker_id=request.sticker_id,
        track_id=sticker_track.id,
        segment_id=sticker_segment.id,
        duration=draft.duration
    )

25.2.2 贴纸片段创建

贴纸片段的创建是服务的核心逻辑，涉及多个参数的配置：

def create_sticker_segment(request: AddStickerRequest, draft) -> StickerSegment:
    """创建贴纸片段"""
    # 基础设置
    clip_settings = ClipSettings(
        start=request.start if request.start is not None else 0,
        end=request.end if request.end is not None else draft.duration,
        scale=request.scale if request.scale is not None else 1.0,
        x=request.x if request.x is not None else 0.5,
        y=request.y if not None else 0.5
    )
    
    # 创建贴纸片段
    sticker_segment = StickerSegment(
        id=f"sticker_{uuid.uuid4().hex}",
        material_id=request.sticker_id,
        clip=clip_settings,
        render_type="sticker",
        source_type="user"
    )
    
    return sticker_segment

25.3 数据结构定义

25.3.1 请求参数模型

贴纸添加服务的请求参数定义在 src/schemas/add_sticker.py 中：

class AddStickerRequest(BaseModel):
    """创建文本富文本样式请求参数"""
    draft_url: str = Field(..., description="草稿URL")
    sticker_id: str = Field(..., description="贴纸素材ID")
    start: int = Field(default=0, description="开始时间，单位：微秒")
    end: int = Field(default=None, description="结束时间，单位：微秒")
    scale: float = Field(default=1.0, description="缩放比例")
    x: float = Field(default=0.5, description="X坐标位置（0-1）")
    y: float = Field(default=0.5, description="Y坐标位置（0-1）")

25.3.2 响应参数模型

class AddStickerResponse(BaseModel):
    """创建文本富文本样式响应参数"""
    draft_url: str = Field(default="", description="草稿URL")
    sticker_id: str = Field(default="", description="贴纸素材ID")
    track_id: str = Field(default="", description="轨道ID")
    segment_id: str = Field(default="", description="片段ID")
    duration: int = Field(default=0, description="草稿总时长，单位：微秒")

25.4 异常处理

贴纸添加服务定义了完善的异常处理机制：

# 无效的草稿URL
INVALID_DRAFT_URL = HTTPException(
    status_code=400,
    detail="无效的草稿URL"
)

# 贴纸添加失败
STICKER_ADD_FAILED = HTTPException(
    status_code=500,
    detail="贴纸添加失败"
)

25.5 API接口定义

在 src/router/v1.py 中定义了贴纸添加的API接口：

@router.post("/addSticker", response_model=AddStickerResponse)
async def add_sticker_endpoint(request: AddStickerRequest):
    """添加贴纸"""
    try:
        return await add_sticker(request)
    except Exception as e:
        logger.error(f"添加贴纸失败: {str(e)}")
        raise STICKER_ADD_FAILED

25.6 使用示例

25.6.1 请求示例

{
    "draft_url": "capcut://draft/123456789",
    "sticker_id": "sticker_12345",
    "start": 0,
    "end": 10000000,
    "scale": 1.2,
    "x": 0.3,
    "y": 0.7
}

25.6.2 响应示例

{
    "draft_url": "capcut://draft/123456789",
    "sticker_id": "sticker_12345",
    "track_id": "track_sticker_001",
    "segment_id": "sticker_abc123",
    "duration": 15000000
}