giggle-generation-drama

⚠️ 安装前请先查看

请在安装前查看。 此技能将：

1. 网络 – 调用 Giggle.pro API 生成视频

要求：python3、GIGGLE_API_KEY（系统环境变量）、pip 包：requests

出错时不要重试：如果脚本执行遇到错误，不要重试。请直接向用户报告错误并停止。

---

首次使用前的必要设置

执行任何操作前，请确认用户已配置 API Key，以避免因身份验证错误导致工作流失败。

• API Key：登录 Giggle.pro。在主站打开左侧边栏，进入 API Key（API 密钥）——在此处创建或复制密钥。不要仅依赖含糊的“账户设置”；侧边栏中的 API Key 区块才是预期的入口。
• 配置：设置系统环境变量 GIGGLE_API_KEY
  • export GIGGLE_API_KEY=your_api_key

验证步骤：

1. 确认用户已在系统环境中配置 GIGGLE_API_KEY。
2. 如果尚未配置，引导用户：

   登录后打开 giggle.pro → 左侧边栏 → API Key / API 密钥 → 创建或复制密钥，然后在终端中运行 export GIGGLE_API_KEY=your_api_key。

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

生成模式

支持三种模式。启动工作流前请让用户选择一种模式。如果用户未指定，默认使用 Episodes 模式（director）。

模式	project_type	描述
Episodes	director	由 AI 执导的短剧，包含分镜和镜头语言
Narration	narration	以旁白为主的视频
Short Film	short-film	故事与视觉效果兼顾的电影风格短片

主要工作流：execute_workflow

使用 execute_workflow 运行完整工作流：提交 + 轮询 + 自动支付（如有需要）+ 等待完成。调用一次并等待返回。

函数内部执行过程（供你理解）： 提交任务 → 大约每 3 秒轮询一次 → 检测待支付状态并在需要时自动支付 → 等待完成（最长约 1 小时）→ 返回视频下载链接或错误。

持续进度更新（阻塞式工作流）

execute_workflow 会阻塞：提交、按需支付和轮询（约每 3 秒一次）都在 Python 调用内部进行（最长约 1 小时）。你无法在轮询间隔内发送聊天消息。

1. 调用前，告知用户短剧／旁白／短片制作流程正在进行，通常需要几分钟到几十分钟，并说明函数返回后会立即再次发送消息——用户无需主动联系你。

2. 发起调用后，无需等待用户询问“进度如何？”，每 10 秒主动向用户推送当前进度，说明正在执行哪个步骤。

3. 调用返回后，成功时立即转发完整的签名视频 URL；失败时立即提供清晰的错误信息。如果 API 提供了 project_id，失败或超时时也请一并提供，供用户后续操作或重试。

4. 非阻塞路径（仅 create_and_submit）：如果用户希望，可以提交并返回 ID——然后仅在用户询问时查询。

函数签名

execute_workflow(
    diy_story: str,                           # Story/script content (required)
    aspect: str,                              # Aspect ratio: 16:9 or 9:16 (required)
    project_name: str,                        # Project name (required)
    language: str,                            # zh or en (required)—see "Language" below
    video_duration: str = "auto",             # Duration, default "auto" (optional)
    style_id: Optional[int] = None,          # Style ID (optional)
    project_type: str = "director",           # Mode, default "director" (optional)
    character_info: Optional[List[Dict]] = None  # Character images (optional)
)

语言（language，必填）

必须为 zh 或 en。根据用户故事／提示词以及当前对话中的主要语言设置：

• 用户主要用中文撰写或口述故事（或你与用户的对话主要使用中文）→ language="zh"。
• 用户主要用英文撰写或口述故事（或对话主要使用英文）→ language="en"。
• 混合语言的故事：选择脚本正文占多数的语言；如果两种语言比例相同，优先选择用户在最近的明确指示中使用的语言。

此值会作为生成语言传递给 Giggle API；不得省略或在未核对内容的情况下猜测。

参数说明

参数	必填	描述
diy_story	是	故事或脚本内容
aspect	是	宽高比：16:9 或 9:16
project_name	是	项目名称
language	是	zh（中文）或 en（英文）——与故事／对话的语言一致（参见上文）
video_duration	否	auto、30、60、120、180、240、300；默认值为 "auto"
style_id	否	风格 ID；未指定时省略
project_type	否	director / narration / short-film；默认值为 "director"
character_info	否	角色图片列表：[{"name": "Character name", "url": "Image URL"}, ...]

使用流程

1. 介绍并选择生成模式（必需）：生成前，必须介绍三种模式并让用户选择。显示：

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

   剧集（director）：由 AI 导演处理分镜和镜头语言。适合包含对白和情节的短剧。

   旁白（narration）：以旁白为主，并配以画面。适合知识分享、新闻评论和产品介绍。

   短片（short-film）：故事与画面并重，采用电影感镜头和节奏。适合情感短片、创意故事和艺术表达。

   等待用户明确选择后再继续。如果用户未指定，默认使用剧集模式。

2. 如果用户想选择风格：调用 get_styles() 获取风格列表；显示 ID、名称、类别和描述；等待用户选择后再继续。

3. 如果用户提供角色图片 URL：为每个角色填写 name 和 url，构建 character_info 数组。

4. 根据 语言 部分，结合故事和后续对话设置 language（zh / en）——必须在调用 execute_workflow 之前完成。

5. 运行工作流：

   • 调用 execute_workflow() 之前，按照上文的持续进度更新要求，发送简短的开始消息和合理的预计时间——函数返回后立即告知用户。
   • 调用 execute_workflow()，传入故事、宽高比、项目名称和 language。
   • 根据所选模式设置 project_type；如果指定了 video_duration，则传入该值，否则传入 "auto"；如果选择了 style_id，则传入该值；如果提供了 character_info，则传入该值。
   • 仅调用一次并等待——该函数会处理创建、提交、轮询、支付和完成；返回下载链接或错误。返回后立即向用户转达成功结果（完整签名 URL）或失败信息。

示例

查看风格列表：

api = TrusteeModeAPI()
styles_result = api.get_styles()
# Display style list to user

基本工作流（无时长、无风格）：

api = TrusteeModeAPI()
result = api.execute_workflow(
    diy_story="An adventure story...",
    aspect="16:9",
    project_name="My Video Project",
    language="en",
)
# result contains download URL or error

指定时长，不指定风格：

result = api.execute_workflow(
    diy_story="An adventure story...",
    aspect="16:9",
    project_name="My Video Project",
    language="en",
    video_duration="60"
)

指定时长和风格：

result = api.execute_workflow(
    diy_story="An adventure story...",
    aspect="16:9",
    project_name="My Video Project",
    language="en",
    video_duration="60",
    style_id=142
)

旁白模式：

result = api.execute_workflow(
    diy_story="Today we'll talk about AI development...",
    aspect="16:9",
    project_name="Narration Video",
    language="en",
    project_type="narration"
)

短片模式：

result = api.execute_workflow(
    diy_story="Sunset. An old fisherman rows home alone. The sea glows red...",
    aspect="16:9",
    project_name="Short Film",
    language="en",
    project_type="short-film"
)

使用角色图片（用户提供角色图片 URL 时）：

result = api.execute_workflow(
    diy_story="Xiao Ming and Xiao Hong meet in the park, they smile at each other...",
    aspect="16:9",
    project_name="Custom Character Video",
    language="zh",
    character_info=[
        {"name": "Xiao Ming", "url": "https://xxx/xiaoming.jpg"},
        {"name": "Xiao Hong", "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

不要从 download_url 中移除 response-content-disposition=attachment 或其他查询参数。不要返回不带查询参数的未签名 URL，例如：

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

失败：

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