Ponyflash

PonyFlash Skill

Step 0: Decide Which Capability Path Applies

This skill now contains two capability families:

1. Cloud generation via PonyFlash Python SDK

   • image generation
   • video generation
   • speech synthesis
   • music generation
   • model listing
   • file management
   • account / credits
   • These tasks require a valid PonyFlash API key.

2. Local media editing via FFmpeg toolchain

   • ffmpeg / ffprobe detection
   • installation planning
   • clip / concat / transcode
   • extract audio / capture frame
   • subtitle capability checks
   • ASS subtitle generation and burn-in workflow
   • 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:
   • image generation
   • video generation
   • speech synthesis
   • music generation
   • local media editing with FFmpeg
3. For complex multi-step productions, there are Creative Playbooks in the playbooks/ directory.
4. To use PonyFlash cloud generation, the user needs an API key:
   • Register / log in at https://www.ponyflash.com
   • Get API key at https://www.ponyflash.com/api-key (starts with rk_)
   • Check credits at https://www.ponyflash.com/usage
   • 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"

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

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

3. If ffmpeg / ffprobe or required filters are missing:

• Tell the user what is missing.
• Ask whether the user wants platform-appropriate FFmpeg installation guidance.
• After the user installs FFmpeg, rerun the dependency checks before continuing.

What this Skill Can Do

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 and display the full list.
3. User's request is clearly a multi-step production task → Suggest a matching playbook from 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 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:

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

Plain local string paths such as "./photo.jpg" are not supported. For local files, always use Path(...) or open(..., "rb").

Generation result

Generation object fields: request_id, status, outputs, usage, error.

Convenience properties:

• gen.url — first output URL (or None)
• gen.urls — list of all output URLs
• gen.credits — credits consumed

Quick Examples (PonyFlash SDK)

Image

gen = pony_flash.images.generate(
    model="nano-banana-pro",
    prompt="A sunset over mountains",
    resolution="2K",
    aspect_ratio="16:9",
)
print(gen.url)

Video

gen = pony_flash.video.generate(
    model="veo-3.1-fast",
    prompt="A timelapse of a city at night",
    duration=4,
    resolution="720p",
    aspect_ratio="16:9",
    generate_audio=False,
)
print(gen.url)

Speech

gen = pony_flash.speech.generate(
    model="speech-2.8-hd",
    input="Hello, welcome to PonyFlash!",
    voice="English_Graceful_Lady",
)
print(gen.url)

Music

gen = pony_flash.music.generate(
    model="music-2.5",
    prompt="An upbeat electronic dance track",
    duration=30,
)
print(gen.url)

List models

page = pony_flash.models.list()
for model in page.items:
    print(f"{model.id} ({model.type})")

Check balance

balance = pony_flash.account.credits()
print(f"Balance: {balance.balance} {balance.currency}")

Local Media Editing with FFmpeg

No PonyFlash API key is needed for local editing, but local FFmpeg capability checks are mandatory.