linkfox-aigc-videogen
根据单张图片或首尾帧及提示词生成 AI 视频,支持动态可用模型选择、异步等待、素材上传和本地视频交付。适用于商品展示、场景动态化、图片转视频和首尾帧过渡;不适用于多参考图视频、图片生成或文本生成。
SKILL.mdskills/linkfox-aigc-videogen/SKILL.md
GitHubAI 生视频(单图与首尾帧)
适用范围
适用
将单张商品图、场景图或首尾帧制作成视频,按用户要求选择当前可用模型并交付本地视频。
场景速查
| 用户表达 | 使用场景 |
|---|---|
| 用这张商品图生成展示视频 | 单图视频:围绕商品描述镜头与动态。 |
| 从这张首帧过渡到尾帧 | 首尾帧视频:按当前模型能力选择。 |
| 看看现在有哪些模型可用 | 模型选择:查看动态名称与能力。 |
| 视频还在处理中,查一下原任务 | 任务续查:保留已创建的任务。 |
边界
多参考图使用 linkfox-aigc-videogen-multi;HappyHorse 系列即使只有一张图,也经该技能的多图入口提交,未挂载时提示安装,不改造成单图/首尾帧请求。图片生成使用 linkfox-aigc-imagegen,文本生成使用 linkfox-aigc-textgen。
接口清单
| 接口 | 端点 | 接口文档 | 对应脚本 | 说明 |
|---|---|---|---|---|
| 创建视频任务 | POST /aigc/videoGenAsync |
references/api.md | scripts/aigc_videogen.py |
提交单图或首尾帧任务。 |
| 查询任务状态 | POST /aigc/taskQuery |
references/api.md | scripts/aigc_videogen.py(自动轮询或导入 query_task 续查原任务) |
查询状态并获取结果。 |
| 获取上传凭证 | POST /oss/getStsVoucherByAPI |
references/file-upload.md | scripts/upload_file.py |
准备本地素材的公开 URL。 |
| 查询模型枚举 | GET ${LINKFOX_AI_API_URL}/image/video/model/config/list?bizType=88 |
references/api.md | scripts/aigc_videogen.py --list-models --inline |
获取当前可用模型枚举及能力。 |
前置条件
先确定首帧、可选尾帧与期望动态。已有公开可访问素材直接复用;本地图片或附件按 文件上传 准备,先明确告知会获得公开 URL 并确认内容可公开,禁止上传敏感或私密内容。素材准备完成后再创建任务。
视频生成流程
- 先通过查询模型枚举获取当前可用模型及能力,并遵循用户选择;仅查询失败时使用文档中的静态列表兜底。
- 准备首帧和可选尾帧;本地素材使用内置上传器,复用同一图片 URL,保留首尾帧对应关系。上传失败停止本次生成,生成脚本不自动上传。
- 按用户要求和 接口定义 组装参数并提交一次。正常生成不额外查询或存档模型配置,不执行提交前能力校验,不静默改模型或参数。
- 创建后保留任务ID,由脚本等待并轮询,成功后下载到会话
media/。异常或超时先报告已知状态和任务ID,不自动重提、换模型或重复上传;续查只查询原任务。 - 将成功交付时
Saved full response:后的本地视频路径交给用户。媒体未交付时按错误摘要及数据文件处理。
执行方式
- 直接调用接口:接口端点、完整参数、响应和错误码见
references/api.md。 - 脚本调用(推荐):
python scripts/aigc_videogen.py '<JSON 参数>' [--inline] [--no-cache]。 - 成本约束:生成算力按所选参数动态计算,详见“算力消耗预估”。同一会话、同一参数组合默认只创建一次任务;业务封装禁用响应缓存,查询始终获取当前状态。失败或无媒体时不自动重建任务或修改参数连续试探;再次生成前说明额外消耗,由用户决定是否继续。
输出策略
- 完整响应保存到会话
data/,视频下载到同一会话media/。会话根目录依次尝试ACPX_WORKSPACES的首个路径、当前工作目录、用户目录、系统临时目录下的linkfox/;<YYYY-MM-DD>/<session>/按日期与会话聚合,<session>优先取SESSION_ID,否则在进程内生成稳定值。正常运行应选择可写工作目录。 - 每次创建和查询分别存档,文件名包含接口标识与纳秒序号,最终结果另存。生成成功仅输出
Saved full response: <本地视频路径数组>;原始响应静默保存,无媒体时才提示诊断路径。 - 生成时
--inline不改变媒体交付协议。目录查询使用配置 JSON 输出,可通过--inline完整展示;上传器按输入顺序输出上传结果,具体见对应接口文档。 - 直接使用公共调用器时显式传
--no-cache:响应不超过 8000 字节时全量输出,超过时输出顶层字段、常见计数与消耗字段、最大列表的长度和前 3 条样本;--inline强制全量打印,仍保存响应文件。生成封装捕获此输出,不把媒体 URL 或上传凭证直接交付给用户。
先通过摘要判断数据是否足够。需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。
异步视频、目录查询和上传器的专用协议见 references/api.md 及其链接文档;生成成功始终只交付本地视频路径。
执行规则
算力消耗预估
生成按所选参数动态计费,算力消耗与模型、时长等参数相关,没有统一固定单价。可参考响应的实际消耗信息;costToken 缺失时脚本按 0 记录,该缺省值不代表免费。
声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。
用户会因算力消耗而支付费用。需要高频调用或用户对消耗量预期不足时,提醒用户,并由用户决定是否继续。
解决认证和算力问题
出现以下情况时,按 references/onboarding.md 的指引处理:
- 未配置接口密钥:
LINKFOX_AGENT_API_KEY和LINKFOXAGENT_API_KEY均为空。 - HTTP 状态码为
401或402。 - 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。
约束与建议
- 模型名称展示:介绍、推荐、确认和解释错误时只使用动态目录的 name;查询失败使用静态兜底的说明名称。禁止向用户展示 videoType、provider、模型 code 或内部渠道名称;MiniMax H3 的多个内部渠道统一展示为 MiniMax H3。
- 动态能力与默认策略:动态目录用于选择,不以静态名单封顶,不自动换模型。默认策略、别名兼容和能力参数见接口文档;无合法默认值时提示选择。
- 视频交付:只展示转存后的本地视频路径,禁止 Read 视频文件、展示 base64 或直接交付带签名且会过期的原始 URL。完整响应静默保存,仅无媒体时提示诊断路径。
- 区分状态:客户端等待超时不等于后端失败或算力回补;保留原任务ID和最后已知状态。空体或非 JSON 只报告上游响应异常,不编造模型不可用原因。
- 配置地址独立:模型目录域名与生成网关各自配置,不根据网关、Key 或环境前缀推断目录地址。目录查询不发送生成密钥或身份头。
使用示例
单图商品展示
用户:用这张商品图做一段展示视频。
选择适合的当前可用模型,准备素材及动态描述,完成生成后提供本地视频路径。
首尾帧过渡
用户:让画面从第一张图过渡到第二张图。
核对当前模型尾帧能力,保留图片顺序后生成;不以静态名单代替当前目录。
查询未完成任务
用户:刚才的视频超时了,继续查这个任务。
只查询原任务,不再次生成或重复上传。具体续查方式见 references/api.md。
使用反馈
当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。
更多优质、专业的跨境电商技能,请访问 LinkFox Skill。