@miketromba/ploof 0.1.4 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version" />
 </p>
 
-Ploof is a CLI for generating and editing creative assets with AI providers. It supports OpenAI image generation, editing, and variations today, with a provider registry designed for audio, video, and broader model marketplaces over time.
+Ploof is a CLI for generating and editing creative assets with AI providers. It supports OpenAI image generation/editing and OpenAI video generation/editing today, plus the legacy OpenAI image variations endpoint when the authenticated project has access. The provider registry is designed for audio and broader model marketplaces over time.
 
 It is built for both developers and AI agents: predictable commands, parseable output, local auth profiles, YAML manifests, parallel execution, and a companion skill.
 
@@ -20,13 +20,17 @@ It is built for both developers and AI agents: predictable commands, parseable o
 | OpenAI auth profiles | Supported |
 | OpenAI image generation | Supported |
 | OpenAI image editing | Supported |
-| OpenAI image variations | Supported |
+| OpenAI image variations | Legacy endpoint; supported when available to the authenticated project |
+| OpenAI video generation | Supported |
+| OpenAI video editing/extensions | Supported |
+| OpenAI video downloads/library/characters | Supported |
 | Context images and masks | Supported |
+| Video references and source videos | Supported |
 | YAML/JSON batch manifests | Supported |
 | Dependency-aware parallel runs | Supported |
 | Agent instructions via `ploof learn` | Supported |
 | Additional providers | Planned |
-| Audio/video generation | Planned |
+| Audio generation | Planned |
 
 ## Install
 
@@ -68,6 +72,14 @@ ploof image edit \
   --prompt "Replace the background with a clean marble countertop" \
   --out assets/edited.png
 
+# Generate and download a video
+ploof video generate \
+  --prompt "Wide tracking shot of a paper city at blue hour" \
+  --model sora-2 \
+  --size 1280x720 \
+  --seconds 4 \
+  --out assets/clip.mp4
+
 # Run a manifest
 ploof run assets.yaml --parallel 4
 ```
@@ -154,7 +166,7 @@ Use repeated `--image` flags for context/reference images. Use `--mask` when the
 
 ## Image Variations
 
-OpenAI image variations use the legacy variations endpoint and default to `dall-e-2`, which is currently the only supported model for that endpoint.
+OpenAI image variations use the legacy variations endpoint and default to `dall-e-2`, which is currently the only supported model for that endpoint. If OpenAI returns a 404 for this command, use `ploof image edit` for image-to-image workflows or try a profile/project with DALL-E 2 variation access.
 
 ```bash
 ploof image variation \
@@ -170,6 +182,71 @@ The plural alias also works:
 ploof image variations --image input.png --out variation.png
 ```
 
+## Video Generation
+
+OpenAI video generation uses the asynchronous Videos API. `ploof video generate` submits a job immediately. If you pass `--out` or `--download`, Ploof waits for completion and downloads the requested asset.
+
+```bash
+ploof video generate \
+  --provider openai \
+  --prompt "Wide tracking shot of a teal coupe on a desert highway" \
+  --model sora-2 \
+  --size 1280x720 \
+  --seconds 4 \
+  --out assets/clip.mp4 \
+  --output json
+```
+
+Useful generation flags:
+
+| Flag | Description |
+| --- | --- |
+| `--model <model>` | Video model, for example `sora-2` or `sora-2-pro` |
+| `--size <size>` | Output resolution, for example `1280x720` |
+| `--seconds <seconds>` | Clip or extension duration |
+| `--input-reference <path-or-url-or-file-id>` | Image reference for the first frame |
+| `--input-reference-file-id <id>` | OpenAI uploaded image file id |
+| `--input-reference-url <url>` | Image URL or data URL reference |
+| `--character <id>` | Reusable character id; repeat for multiple characters |
+| `--wait` | Poll until the job reaches a terminal status |
+| `--download` | Download after waiting |
+| `--variant <variant>` | `video`, `thumbnail`, or `spritesheet` |
+| `--poll-interval <seconds>` | Polling interval while waiting |
+| `--timeout <seconds>` | Maximum wait time |
+| `--param key=value` | Provider-specific pass-through parameter |
+| `--json '{...}'` | Provider-specific JSON object |
+
+If you omit `--model`, Ploof defaults OpenAI video generation to `sora-2`.
+
+## Video Editing And Library
+
+```bash
+ploof video edit \
+  --video-id video_abc123 \
+  --prompt "Shift the palette to teal and rust" \
+  --out assets/edit.mp4
+
+ploof video extend \
+  --video-id video_abc123 \
+  --prompt "Continue as the camera rises over the rooftops" \
+  --seconds 4 \
+  --out assets/extended.mp4
+
+ploof video download video_abc123 --variant thumbnail --out assets/thumb.webp
+ploof video status video_abc123 --output json
+ploof video list --limit 20 --output json
+ploof video delete video_abc123
+```
+
+OpenAI video edits accept either `--video-id <id>` for an existing completed OpenAI video or `--video <path>` for an uploaded source video when the authenticated project is eligible for that workflow. Extensions accept a source video id or upload, plus a prompt and `--seconds`.
+
+Reusable character commands:
+
+```bash
+ploof video character create --name Mossy --video character.mp4 --output json
+ploof video character get char_abc123 --output json
+```
+
 ## Batch Manifests
 
 ```yaml
@@ -205,6 +282,18 @@ tasks:
       images:
         - task: base
     output: assets/variation.png
+
+  - id: clip
+    kind: video.generate
+    provider: openai
+    prompt: "Slow dolly shot through a miniature paper city"
+    params:
+      model: sora-2
+      size: 1280x720
+      seconds: "4"
+    wait: true
+    download: true
+    output: assets/clip.mp4
 ```
 
 Run it:
@@ -283,7 +372,7 @@ bun run build
 npm pack --dry-run
 ```
 
-The default test suite includes mocked OpenAI end-to-end tests. Those tests run real `ploof` CLI commands against a local mock OpenAI server and verify generated files, edit uploads, sidecar metadata, and dependency-aware manifests without spending API credits.
+The default test suite includes mocked OpenAI end-to-end tests. Those tests run real `ploof` CLI commands against a local mock OpenAI server and verify generated files, edit uploads, video job polling/downloads, sidecar metadata, and dependency-aware manifests without spending API credits.
 
 Live OpenAI tests are opt-in only:
 

package/SPEC.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-Ploof is an npm-published CLI for generating and editing assets through AI generation providers. It starts with OpenAI image generation and editing, but the architecture must support multiple authenticated providers, multiple asset modalities, provider-specific settings, and parallel execution across mixed jobs.
+Ploof is an npm-published CLI for generating and editing assets through AI generation providers. It starts with OpenAI image and video generation/editing, but the architecture must support multiple authenticated providers, multiple asset modalities, provider-specific settings, and parallel execution across mixed jobs.
 
 The product should feel like a small, sharp developer tool: easy to run manually, predictable in scripts, and optimized for AI agents.
 
@@ -87,6 +87,16 @@ Initial capabilities:
 - `image.generate`
 - `image.edit`
 - `image.variation`
+- `video.generate`
+- `video.edit`
+- `video.extend`
+- `video.remix`
+- `video.status`
+- `video.download`
+- `video.list`
+- `video.delete`
+- `video.character.create`
+- `video.character.get`
 
 Future providers should be added through the provider registry without changing the manifest model.
 
@@ -223,8 +233,75 @@ ploof image variation \
   --size 1024x1024
 ```
 
-OpenAI variations default to `dall-e-2`, because the current OpenAI variations
-endpoint only supports that model. `ploof image variations` is an alias.
+OpenAI variations default to `dall-e-2`, because the legacy OpenAI variations
+endpoint only supports that model. This endpoint is supported when the
+authenticated project has DALL-E 2 variation access; if OpenAI returns a 404,
+use `ploof image edit` for image-to-image workflows. `ploof image variations`
+is an alias.
+
+### Video Generation
+
+OpenAI video generation uses the asynchronous Videos API. `ploof video generate`
+submits a job; passing `--out` or `--download` makes Ploof poll until a terminal
+status and download the requested asset.
+
+```bash
+ploof video generate \
+  --provider openai \
+  --prompt "Wide tracking shot of a paper city at blue hour" \
+  --model sora-2 \
+  --size 1280x720 \
+  --seconds 4 \
+  --out assets/clip.mp4 \
+  --output json
+```
+
+First-class OpenAI video flags:
+
+- `--model <model>`
+- `--size <size>`
+- `--seconds <seconds>`
+- `--input-reference <path-or-url-or-file-id>`
+- `--input-reference-file-id <id>`
+- `--input-reference-url <url>`
+- `--character <id>`
+- `--wait`
+- `--download`
+- `--variant video|thumbnail|spritesheet`
+- `--poll-interval <seconds>`
+- `--timeout <seconds>`
+- `--param key=value`
+- `--json '{...}'`
+
+OpenAI video generation defaults to `sora-2` when no model is specified.
+
+### Video Editing And Library
+
+```bash
+ploof video edit \
+  --video-id video_abc123 \
+  --prompt "Shift the palette to teal and rust" \
+  --out assets/edit.mp4
+
+ploof video extend \
+  --video-id video_abc123 \
+  --prompt "Continue as the camera rises over the rooftops" \
+  --seconds 4 \
+  --out assets/extended.mp4
+
+ploof video download video_abc123 --variant thumbnail --out assets/thumb.webp
+ploof video status video_abc123 --output json
+ploof video list --limit 20 --output json
+ploof video delete video_abc123
+ploof video character create --name Mossy --video character.mp4 --output json
+ploof video character get char_abc123 --output json
+```
+
+Video edits accept either `--video-id <id>` for an existing completed OpenAI
+video or `--video <path>` for an uploaded source video when the authenticated
+project is eligible for that workflow. Extensions accept a source video id or
+upload, plus a prompt and `--seconds`. `video remix` is supported for the SDK's
+legacy remix endpoint, but new integrations should prefer `video edit`.
 
 ### Batch Run
 
@@ -267,6 +344,18 @@ tasks:
       images:
         - task: base
     output: assets/variation.png
+
+  - id: clip
+    kind: video.generate
+    provider: openai
+    prompt: "Slow dolly shot through a miniature paper city"
+    params:
+      model: sora-2
+      size: 1280x720
+      seconds: "4"
+    wait: true
+    download: true
+    output: assets/clip.mp4
 ```
 
 ## Asset Input Model
@@ -294,6 +383,11 @@ OpenAI image editing maps:
 - `role=image` to image input files.
 - `role=mask` to mask file.
 
+OpenAI video generation/editing maps:
+
+- `role=reference` to `input_reference` for image-guided video generation.
+- `role=video` to source video uploads for eligible edit/extension workflows.
+
 Future providers can map roles such as `reference`, `style`, `init-image`, `audio`, or `video` differently.
 
 ## Provider Architecture
@@ -307,6 +401,16 @@ type Provider = {
   runImageGenerate(job, context): Promise<ProviderResult>
   runImageEdit(job, context): Promise<ProviderResult>
   runImageVariation(job, context): Promise<ProviderResult>
+  runVideoGenerate(job, context): Promise<ProviderResult>
+  runVideoEdit(job, context): Promise<ProviderResult>
+  runVideoExtend(job, context): Promise<ProviderResult>
+  runVideoRemix(job, context): Promise<ProviderResult>
+  runVideoStatus(job, context): Promise<ProviderResult>
+  runVideoDownload(job, context): Promise<ProviderResult>
+  runVideoList(job, context): Promise<ProviderResult>
+  runVideoDelete(job, context): Promise<ProviderResult>
+  runVideoCharacterCreate(job, context): Promise<ProviderResult>
+  runVideoCharacterGet(job, context): Promise<ProviderResult>
 }
 ```