ponyflash

PonyFlash Skill

Step 0: Decide Which Capability Path Applies

This skill now contains two capability families:

1. Cloud generation via PonyFlash Python SDK
2. image generation
3. video generation
4. speech synthesis
5. music generation
6. model listing
7. file management
8. account / credits
9. These tasks require a valid PonyFlash API key.

1. Local media editing via FFmpeg toolchain
2. ffmpeg / ffprobe detection
3. installation planning
4. clip / concat / transcode
5. extract audio / capture frame
6. subtitle capability checks
7. ASS subtitle generation and burn-in workflow
8. These tasks do NOT require a PonyFlash API key, but they do require local ffmpeg / ffprobe support.

Before doing anything, classify the request:

• If the user is asking to generate media with PonyFlash models, follow the SDK path and require API key setup.
• If the user is asking to edit or process local media, follow the FFmpeg path and do dependency checks first.
• If the user wants an end-to-end production workflow, you may use both: generate assets with PonyFlash, then assemble or export with FFmpeg.

Step 1A: API Key Setup for PonyFlash SDK Tasks

Only do this section when the request needs PonyFlash cloud capabilities.

The FIRST time this skill is activated for a cloud generation task, tell the user the following in your own words:

1. PonyFlash skill is ready to use.
2. It can handle:
3. image generation
4. video generation
5. speech synthesis
6. music generation
7. local media editing with FFmpeg
8. For complex multi-step productions, there are Creative Playbooks in the playbooks/ directory.
9. To use PonyFlash cloud generation, the user needs an API key:
10. Register / log in at https://www.ponyflash.com
11. Get API key at https://www.ponyflash.com/api-key (starts with rk_)
12. Check credits at https://www.ponyflash.com/usage
13. Paste the key back in the chat

On subsequent SDK activations, check whether PONYFLASH_API_KEY is set in the environment. If not, ask the user for the key again.

Once received, set it up:

export PONYFLASH_API_KEY="rk_xxx"

Then install the SDK:

pip install ponyflash

Always verify the key works before any generation task:

from ponyflash import PonyFlash

pony_flash = PonyFlash(api_key="<key from user>")
balance = pony_flash.account.credits()
print(f"Balance: {balance.balance} {balance.currency}")

If verification fails:

• Key invalid or missing → direct user to https://api.ponyflash.com/api-key
• Balance is zero → direct user to https://api.ponyflash.com/usage to top up credits

Step 1B: Local Dependency Setup for FFmpeg Tasks

Only do this section when the request needs local editing, subtitle, or export work.

1. First check local dependencies:

bash "{baseDir}/scripts/check_ffmpeg.sh"

1. If the task involves subtitles, do capability checks, not just existence checks:

bash "{baseDir}/scripts/check_ffmpeg.sh" --require-subtitles-filter

1. If ffmpeg / ffprobe or required filters are missing:
2. Tell the user what is missing.
3. Ask whether the user wants platform-appropriate FFmpeg installation guidance.
4. After the user installs FFmpeg, rerun the dependency checks before continuing.

What this Skill Can Do

| Capability | Resource | Description | |---|---|---| | Image generation | pony_flash.images | Text-to-image, image editing with mask/reference images | | Video generation | pony_flash.video | Text-to-video, first-frame-to-video, OmniHuman, Motion Transfer | | Speech synthesis | pony_flash.speech | Text-to-speech with voice cloning, emotion control, speed, pitch | | Music generation | pony_flash.music | Text-to-music with lyrics, style, instrumental mode, continuation | | Model listing | pony_flash.models | List available models, get model details and supported modes | | File management | pony_flash.files | Upload, list, get, delete files | | Account | pony_flash.account | Check credit balance, get recharge link | | Local media editing | scripts/media_ops.sh | Clip, concat, transcode, extract audio, frame capture | | FFmpeg environment checks | scripts/check_ffmpeg.sh | Detect ffmpeg / ffprobe and subtitle capabilities | | Subtitle font prep | scripts/ensure_subtitle_fonts.sh | Keep a reusable local copy of the default subtitle font when explicitly requested | | ASS subtitle prep | scripts/build_ass_subtitles.py | Adaptive ASS subtitle generation with pre-wrapping |

Creative Playbooks (production workflows)

The playbooks/ directory contains Creative Playbooks — step-by-step production workflow guides for specific content types. Playbooks act as a director layer: they tell you what to create and in what order, while this SKILL.md tells you how to execute generation and editing.

When to use a playbook

1. User explicitly requests a playbook by name → Read the corresponding file from playbooks/ and follow its workflow.
2. User asks to see available playbooks → Read [playbooks/INDEX.md](playbooks/INDEX.md) and display the full list.
3. User's request is clearly a multi-step production task → Suggest a matching playbook from [playbooks/INDEX.md](playbooks/INDEX.md) and ask whether to use it.
4. User's request is a single-step generation or editing task → Proceed directly with the relevant SDK or FFmpeg capability. No playbook needed.

How to execute a playbook

Once a playbook is loaded:

• Follow its workflow (asset prep → content generation → voice / music → editing → output).
• Use PonyFlash SDK for generation tasks and FFmpeg scripts for local assembly / export tasks.
• Confirm key creative decisions with the user before expensive generation.
• Adapt prompts, durations, output format, and export strategy to the user's actual goal.

Creating custom playbooks

When the user asks to create a new playbook, generate a markdown file in playbooks/ following this template:

---
name: Playbook Name
description: One-line summary of what this playbook produces
tags: [keyword1, keyword2, keyword3]
difficulty: beginner | intermediate | advanced
estimated_credits: credit range estimate
output_format: format description (e.g., "vertical 9:16 MP4")
---

# Playbook Name

## Use Cases
When to use this playbook.

## Workflow
### Step 1: Asset Preparation
What the user needs to provide; how to generate missing assets.

### Step 2: Visual Content Generation
Which models to use, recommended parameters, prompt guidance.

### Step 3: Voice / Music
Speech synthesis + background music guidance.

### Step 4: Editing / Assembly
How to assemble, trim, subtitle, transcode, and export with the local FFmpeg workflow.

### Step 5: Output / Optimization
Render settings, format recommendations.

## Prompt Templates
Reusable prompt examples for this content type.

## Notes
Best practices, common pitfalls.

After creating the file, update [playbooks/INDEX.md](playbooks/INDEX.md) to include the new playbook.

PonyFlash SDK Core Concepts

Client initialization

from ponyflash import PonyFlash

pony_flash = PonyFlash(api_key="rk_xxx")

Reads PONYFLASH_API_KEY from environment if api_key is omitted.

FileInput — zero-friction file handling

All file parameters accept any of these types:

| Input type | Example | Behavior | |---|---|---| | URL string | "https://example.com/photo.jpg" | Passed directly to API | | file_id string | "file_abc123" | Passed directly to API | | Path object | Path("photo.jpg") | Auto-uploaded via presigned URL | | open() file | open("photo.jpg", "rb") | Auto-uploaded via presigned URL | | bytes | image_bytes | Auto-uploaded via presigned URL | | (filename, bytes) tuple | ("photo.jpg", data) | Auto-uploaded with filename |

Temp uploads are cleaned up automatically after generate() completes.

Plain