技能介绍

解决什么问题

房产经纪人每天要为多套房源制作推广视频。传统流程是：拍摄房间实景 → 手动录制口播解说 → 后期加字幕 → 导出成片。每套房源重复一遍，十分钟的视频可能要花半小时剪辑。更麻烦的是，口播内容往往缺少结构化信息——小区名称、户型、面积、楼层这些关键数据，观众看完视频未必记得住。

这个技能的思路是：把空镜视频和房源文字信息自动融合，用 Coze 工作流把结构化字段渲染成专业字幕，直接叠加到实拍画面上。你只需要提供视频和文字参数，剩下的交给 API。

核心能力与工作流程

输入参数：

video_url：房产实拍视频链接（必填）
community_name：小区名称（必填）
layout：户型，如三室两厅两卫（必填）
area：面积，如120平米（必填）
floor：楼层信息，如中楼层/18层（必填）
description：补充描述，如精装修、南北通透（可选）

执行流程：

核心脚本是 scripts/run_workflow.py，它负责三件事：构建请求参数、调用 Coze 工作流 API、解析返回结果。脚本支持 --token 和 --timeout 两个可选参数，分别用于覆盖环境变量和调整超时时间。

工作流执行后返回 JSON 格式结果，包含执行状态、HTTP 状态码和输出数据。成功时 data 字段给出生成视频的下载 URL；失败时 error 字段包含 Coze 特有的 error_code 和 error_message。

与贝壳 Agent 联动：

如果你已经在贝壳二手房搜索结果里有了房源数据，技能可以直接从结果中提取 community_name、layout、area、floor 等字段，不需要你再重复输入。你只需要补充视频文件就行。

适用边界与注意点

视频要求：

时长 1-5 分钟，支持 MP4/MOV 等常见格式
视频 URL 必须可公开访问，API 会先验证 URL 可达性

Token 配置：

API Token 通过 Windows 用户级环境变量 COZE_VIDEO_API_TOKEN 持久化配置。新终端会话自动继承，不需要重复设置。如果需要更新 Token，可以通过 PowerShell 修改环境变量，或者在调用脚本时用 --token 参数临时覆盖。

常见错误处理：

脚本内置了错误码转换逻辑。已知的 Coze 错误码 201005 表示视频 URL 不可访问，通常是因为链接未公开或需要鉴权。超时问题可以通过 --timeout 参数调整，默认 300 秒（5 分钟）。

输出结果：

成功时，脚本返回的 JSON 中 data 字段包含生成视频的下载 URL 或文件路径，你可以直接用这个链接分发到朋友圈、抖音或房源平台。失败时，根据 error_code 和 error_message 排查原因——大部分问题集中在视频格式不支持、URL 无效或 Token 缺失这几类。