|
| 1 | +# How to use Video generation |
| 2 | + |
| 3 | +Powerful video generation models such as `sora-2` are available through PSOpenAI. These cmdlets let you request new clips, monitor their progress, download finished assets, remix existing videos, and clean up jobs when you are done. |
| 4 | + |
| 5 | +OpenAI's official documentation for videos is here. |
| 6 | +https://platform.openai.com/docs/guides/video-generation |
| 7 | + |
| 8 | +This guide shows end-to-end workflows and reusable snippets for each video-related cmdlet. |
| 9 | + |
| 10 | + |
| 11 | +## Functions overview |
| 12 | + |
| 13 | +| Scenario | Cmdlet | What it does | |
| 14 | +| ---------------------- | ------------------ | -------------------------------------------------------------------------------------- | |
| 15 | +| Create a new job | `New-Video` | Submits a prompt, model, duration, and resolution to start rendering. | |
| 16 | +| Retrieve job status | `Get-Video` | Retrieves a single job or lists jobs. | |
| 17 | +| Download assets | `Get-VideoContent` | Fetches the generated video, thumbnail, or spritesheet. | |
| 18 | +| Remix an existing clip | `New-VideoRemix` | Applies a new prompt to a existing video without regenerating everything from scratch. | |
| 19 | +| Delete a job | `Remove-Video` | Removes a job you no longer need. | |
| 20 | + |
| 21 | +## Prerequisites |
| 22 | + |
| 23 | +1. Import the module and set your API key. |
| 24 | + ```powershell |
| 25 | + Import-Module ..\PSOpenAI.psd1 -Force |
| 26 | + $env:OPENAI_API_KEY = '<Put your API key here>' |
| 27 | + ``` |
| 28 | + |
| 29 | +## Generate and download a video |
| 30 | + |
| 31 | +The script below creates a four-second vertical clip, waits until it finishes, and writes the MP4 to disk. |
| 32 | + |
| 33 | +```powershell |
| 34 | +# Start a new video generation job. |
| 35 | +$VideoJob = New-Video ` |
| 36 | + -Prompt 'A hummingbird drinking nectar in super slow motion, macro lens.' ` |
| 37 | + -Model 'sora-2' ` |
| 38 | + -Seconds 4 ` |
| 39 | + -Size 720x1280 |
| 40 | +
|
| 41 | +# Wait for completion. |
| 42 | +while ($true) { |
| 43 | + Start-Sleep -Seconds 5 |
| 44 | + $current = Get-Video -VideoId $VideoJob.id |
| 45 | + "[{0}] status = {1}, progress = {2}%" -f (Get-Date), $current.status, $current.progress |
| 46 | + if ($current.status -in @('completed', 'failed')) { break } |
| 47 | +} |
| 48 | +
|
| 49 | +# Download the generated video. |
| 50 | +$videoPath = Join-Path $PWD 'hummingbird.mp4' |
| 51 | +Get-VideoContent -VideoId $VideoJob.id -OutFile $videoPath |
| 52 | +``` |
| 53 | + |
| 54 | +Above example uses `New-Video` to start a job, then waits until the job completes by polling `Get-Video` every five seconds. Finally, it downloads the MP4 file with `Get-VideoContent`. |
| 55 | + |
| 56 | +More simply, you can use `-WaitForCompletion` on `Get-VideoContent` to block until the job finishes and download the file in one step. |
| 57 | + |
| 58 | +```powershell |
| 59 | +New-Video -Model 'sora-2' -Prompt 'A cat flying with butterfly wings' -Seconds 4 -Size 1280x720 | ` |
| 60 | + Get-VideoContent -OutFile (Join-Path $PWD 'flying_cat.mp4') -WaitForCompletion |
| 61 | +``` |
| 62 | + |
| 63 | +## Remix an existing video |
| 64 | + |
| 65 | +Once you have a completed job, apply targeted changes with `New-VideoRemix`. |
| 66 | + |
| 67 | +```powershell |
| 68 | +# Assume you have a completed video job with ID 'video_abc123'. |
| 69 | +$sourceJob = Get-Video -VideoId 'video_abc123' |
| 70 | +
|
| 71 | +$remixJob = New-VideoRemix ` |
| 72 | + -VideoId $sourceJob.id ` |
| 73 | + -Prompt 'Replace the background with a vibrant cherry blossom garden, keep the subject intact.' |
| 74 | +
|
| 75 | +$remixJob | Get-VideoContent -OutFile (Join-Path $PWD 'cherry_blossom_remix.mp4') -WaitForCompletion |
| 76 | +``` |
| 77 | + |
| 78 | +`New-VideoRemix` takes both the prompt and the source `VideoId`, so you can keep the structure of the original clip while updating specific elements. The resulting job behaves like any other video job, you can wait on it and download content the same way. |
| 79 | + |
| 80 | +## List and clean up jobs |
| 81 | + |
| 82 | +Use the list parameter set on `Get-Video` to review existing jobs and `Remove-Video` to delete ones you no longer need. |
| 83 | + |
| 84 | +```powershell |
| 85 | +# Show the 5 most recent jobs. |
| 86 | +Get-Video -Limit 5 -Order desc | |
| 87 | + Select-Object id, status, created_at, expires_at |
| 88 | +
|
| 89 | +# Delete all jobs that have already expired. |
| 90 | +Get-Video -All | |
| 91 | + Where-Object expires_at -le (Get-Date) | |
| 92 | + Remove-Video |
| 93 | +``` |
| 94 | + |
| 95 | +`Remove-Video` accepts IDs from the pipeline so you can compose cleanup flows easily. |
0 commit comments