简体中文 | English

⚠️ 安装前请务必审阅

请在安装前仔细审阅以下内容。 本技能将：

1. 网络请求 — 调用 Giggle.pro API 进行视频生成

依赖要求： python3、系统环境变量 GIGGLE_API_KEY、pip 包：requests

出错不重试：若脚本执行过程中发生错误，不得重试。应直接向用户报告错误并终止流程。

首次使用前的必要配置

执行任何操作前，请确认用户已正确配置 API Key，以避免因鉴权失败导致工作流中断。

• API Key：登录 Giggle.pro，在账户设置中获取 API Key。
• 配置方式：设置系统环境变量 GIGGLE_API_KEY
  • export GIGGLE_API_KEY=your_api_key

验证步骤：

1. 确认用户已在系统环境中配置 GIGGLE_API_KEY。
2. 若未配置，需引导用户完成配置：

   您好！在使用视频生成功能前，您需要先配置 API Key。请前往 Giggle.pro 获取您的 API Key，然后在终端中运行 export GIGGLE_API_KEY=your_api_key。

3. 等待用户完成配置后，再继续后续工作流。

生成模式

支持三种生成模式。启动工作流前，必须向用户说明并请其选择一种模式。若用户未明确指定，则默认采用 Episodes 模式（director）。

主工作流：execute_workflow

调用 execute_workflow 执行完整工作流：提交任务 + 轮询进度 + 自动支付（如需）+ 等待完成。仅需调用一次，并等待其返回结果。

1. 提交生成任务
2. 每 3 秒轮询一次任务进度
3. 检测待支付状态并自动完成支付（如需）
4. 等待任务完成（最长 1 小时）
5. 返回视频下载链接或错误信息

函数签名

execute_workflow(
    diy_story: str,                           # 故事/脚本内容（必填）
    aspect: str,                              # 画幅比例：16:9 或 9:16（必填）
    project_name: str,                        # 项目名称（必填）
    video_duration: str = "auto",             # 视频时长，默认为 "auto"（选填）
    style_id: Optional[int] = None,          # 风格 ID（选填）
    project_type: str = "director",           # 生成模式，默认为 "director"（选填）
    character_info: Optional[List[Dict]] = None  # 角色图像列表（选填）
)

参数说明

使用流程

1. 介绍并选择生成模式（必需）：生成前，必须向用户清晰介绍三种模式，并请其做出明确选择。展示如下内容：

   我们支持三种视频生成模式，请选择：

   Episodes（director）：AI 导演自动处理分镜脚本与镜头语言，适合含对白与剧情的短剧。

   Narration（narration）：以旁白为核心，辅以匹配画面，适合知识分享、新闻评论、产品介绍等场景。

   Short Film（short-film）：故事性与画面表现力均衡，具备电影级镜头调度与节奏把控，适合情感短片、创意叙事及艺术表达。

   须等待用户明确选择后方可继续。若用户未指定，则默认采用 Episodes 模式。

2. 若用户希望选择风格：调用 get_styles() 获取风格列表；向用户展示每个风格的 ID、名称、分类与描述；等待用户选定后再继续。

3. 若用户提供角色图像 URL：按每位角色构造 character_info 数组，每项包含 name 与 url 字段。

4. 执行工作流：

   • 调用 execute_workflow()，传入故事内容、画幅比例、项目名称。
   • 根据用户所选模式设置 project_type；若用户指定了时长，则传入 video_duration（否则使用默认值 "auto"）；若用户选择了风格，则传入 style_id；若提供了角色图像，则传入 character_info。
   • 仅调用一次并等待返回 — 该函数内部已封装任务创建、提交、轮询、支付及完成检测全流程；最终返回视频下载链接或错误信息。

示例

查看风格列表：

api = TrusteeModeAPI()
styles_result = api.get_styles()
# 向用户展示风格列表

基础工作流（不指定时长、不指定风格）：

api = TrusteeModeAPI()
result = api.execute_workflow(
    diy_story="一个冒险故事...",
    aspect="16:9",
    project_name="我的视频项目"
)
# result 中包含下载 URL 或错误信息

指定时长、不指定风格：

result = api.execute_workflow(
    diy_story="一个冒险故事...",
    aspect="16:9",
    project_name="我的视频项目",
    video_duration="60"
)

指定时长与风格：

result = api.execute_workflow(
    diy_story="一个冒险故事...",
    aspect="16:9",
    project_name="我的视频项目",
    video_duration="60",
    style_id=142
)

Narration 模式：

result = api.execute_workflow(
    diy_story="今天我们来聊聊 AI 开发...",
    aspect="16:9",
    project_name="旁白视频",
    project_type="narration"
)

Short Film 模式：

result = api.execute_workflow(
    diy_story="夕阳西下。一位老渔夫独自划船归家。海面泛着红光...",
    aspect="16:9",
    project_name="短片创作",
    project_type="short-film"
)

带角色图像（当用户提供角色图像 URL 时）：

result = api.execute_workflow(
    diy_story="小明和小红在公园相遇，彼此微笑...",
    aspect="16:9",
    project_name="自定义角色视频",
    character_info=[
        {"name": "小明", "url": "https://xxx/xiaoming.jpg"},
        {"name": "小红", "url": "https://xxx/xiaohong.jpg"}
    ]
)

返回值

该函数为阻塞式调用，将一直等待至任务完成（成功或失败）或超时（1 小时）。请务必等待其返回结果。

成功响应（含下载链接）：

{
    "code": 200,
    "msg": "success",
    "uuid": "...",
    "data": {
        "project_id": "...",
        "video_asset": {...},
        "status": "completed"
    }
}

请向用户返回 完整的带签名 URL（即 data.video_asset.download_url），例如：

https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4?Policy=...&Key-Pair-Id=...&Signature=...&response-content-disposition=attachment

请勿返回不含查询参数的未签名 URL，例如：

https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4

失败响应：

{
    "code": -1,
    "msg": "Error message",
    "data": null
}