giggle-generation-drama

Files (3)

• SKILL.md
• requirements.txt · scripts/
• trustee_api.py · scripts/

SKILL.md (first lines)

## ⚠️ Review Before Installing

**Please review before installing.** This skill will:

1. **Network** – Calls Giggle.pro API for video generation

**Requirements**: `python3`, `GIGGLE_API_KEY` (system environment variable), pip packages: `requests`

> **No Retry on Error**: If script execution encounters an error, **do not retry**. Report the error to the user directly and stop.

---

## Required Setup Before First Use

Before performing any operation, confirm the user has configured the API Key to avoid workflow failure due to auth errors.

- **API Key**: Log in to [Giggle.pro](https://giggle.pro/). On the **main site**, open the **left sidebar** and go to **API Key** (**API 密钥**) — create or copy your key there. **Do not** rely on vague “account settings” alone; the sidebar **API Key** block is the intended entry point.
- **Configuration**: Set system environment variable `GIGGLE_API_KEY`
  - `export GIGGLE_API_KEY=your_api_key`

**Verification steps**:

1. Confirm the user has configured `GIGGLE_API_KEY` in system environment.
2. If not configured, **guide the user**:
   > Open [giggle.pro](https://giggle.pro/) while logged in → **left sidebar** → **API Key** / **API 密钥** → create or copy your key, then run `export GIGGLE_API_KEY=your_api_key` in the terminal.
3. Wait for the user to configure before continuing the workflow.

## Generation Modes

Supports three modes. **Ask the user to select a mode before starting the workflow**. If not specified, default to **Episodes mode** (`director`).

| Mode | project_type | Description |
|------|--------------|-------------|
| **Episodes** | `director` | AI-directed short drama with storyboards and shot language |
| **Narration** | `narration` | Narration-focused video |
| **Short Film** | `short-film` | Story and visuals balanced; cinematic short film |

## Main Workflow: execute_workflow

Use `execute_workflow` to run the full workflow: submit + poll + auto-pay (if needed) + wait for completion. Call once and wait for return.

**Inside the function (for your mental model):** submit task → poll about every 3 seconds → detect pending payment and auto-pay if needed → wait for completion (max ~1 hour) → return video download link or error.

### Continuous progress updates (blocking workflow)

`execute_workflow` **blocks**: submit, pay if needed, and poll (~every 3s) are all **inside** the Python call (up to **~1 hour**). You cannot send per-poll chat between ticks.

1. **Before the call**, inform the user that the **short drama/narration/short film production process** is in progress, typically taking **a few minutes to tens of minutes**, and that a message will be sent again immediately after **function is restored**—the user does not need to contact you proactively.

2. **Initiate the call**, without waiting for the user to ask "Any progress?", proactively push the current progress to the user every 10 seconds, showing which step is currently being done.

3. **After the call is restored**, immediately forward the **complete signed video URL** upon success or a clear error; if the API exposes **`project_id`**, also provide this information upon failure/timeout for the user's subsequent operations or retry.

4. **Non-blocking path** (`create_and_submit` only): If the user wishes, you can submit and return the ID—then query it only when the user inquires.

### Function Signature

```python
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 (`language`, required)

Must be **`zh`** or **`en`**. Set it from the **dominant language of the user’s story/prompt and the current dialogue**:

- User writes or dictates the story **mainly in Chinese** (or your conversation with them is **mainly Chinese**) → `language="zh"`.
- User writes or dictates the story **mainly in English** (or the conversation is **mainly English**) → `language="en"`.
- **Mixed story**: choose the language of the **majority of the script body**; if evenly mixed, prefer the language the user used for **the latest explicit instructions**.

This value is passed to the Giggle API as the generation language; it must **not** be omitted or guessed without matching the content.

### Parameter Description

| Parameter | Required | Description |
|-----------|----------|-------------|
| diy_story | yes | Story or script content |
| aspect | yes | Aspect ratio: `16:9` or `9:16` |
| project_name | yes | Project name |
| language | yes | `zh` (Chinese) or `en` (English)—aligned with story/dialogue (see above) |
| video_duration | no | `auto`, `30`, `60`, `120`, `180`, `240`, `300`; default `"auto"` |
| style_id | no | Style ID; omit if not specified |
| project_type | no | `director` / `narration` / `short-film`; default `"director"` |
| character_info | no | Character image list: `[{"name": "Character name", "url": "Image URL"}, ...]` |

### Usage Flow

1. **Introduce and select generation mode** (required): Before generating, **must introduce the three modes** and let the user choose. Display:

   > We support three video generation modes. Please choose:
   >
   > **Episodes (director)**: AI director handles storyboards and shot language. Good for short drama with dialogue and plot.
   >
   > **Narration (narration)**: Narration-focused with visuals. Good for knowledge sharing, news commentary, product introductions.
   >
   > **Short Film (short-film)**: Story and visuals balanced; cinematic shots and pacing. Good for emotional shorts, creative stories, artistic expression.

   Wait for explicit user choice before continuing. If not specified, default to Episodes.

2. **If the user wants to pick a style**: Call `get_styles()` for the style list; show ID, name, category, description; wait for choice before continuing.
3. **If the user provides character image URLs**: Build `character_info` array with `name` and `url` per character.
4. **Set `language` (`zh` / `en`)** per **Language** section from the story and ongoing dialogue—**required before** `execute_workflow`.
5. **Run workflow**:
   - **Before** calling `execute_workflow()`, follow **Continuous progress updates** above: brief start message, realistic ETA—**you will report as soon as it returns**.
   - Call `execute_workflow()` with story, aspect ratio, project name, **and `language`**.
   - Set `project_type` per chosen mode; pass `video_duration` if specified (else `"auto"`); pass `style_id` if chosen; pass `character_info` if provided.
   - **Call once and wait** — the function handles create, submit, poll, pay, and completion; returns download link or error. **Immediately** after return, forward success (full signed URL) or failure to the user.

### Examples

**View style list**:

From giggle-official/skills, MIT.

More from giggle-official/skills