Video and imagesfrom the command line
A small command for scripts and AI agents. It signs in with a code you confirm in a browser, prices every job before it runs, waits for the result and saves the file. Underneath it calls the public API, and it spends your creative balance, like the studio.
The tool is not yet published. The commands below show how it works; the install command will appear here once it is released.
Connecting your own AI agent is open to every account and needs no key. Developer API keys, for automating your own work from code, are by application.
Sign in oncethen one command per result
Each command does the whole job: price, submit, wait, save. Progress goes to standard error, so a script reads only the result.
- 01 · Sign in
A link and a code, nothing pasted
pershot login prints a link and a short code. Open the link in any browser, sign in, check that the code matches and allow it. The tool then receives a sign-in made for it and keeps it in a file only you can read. It works the same on a server or in a sandbox.
pershot login # Prints a link and a short code. Open the link in any browser, # check that the code matches and allow it. The key is saved for you. pershot whoami # which key and server are in useIt needs a verified email only. The sign-in appears under AI connections, where you can cap or revoke it, and it spends your creative balance, like the studio.
- 02 · Video
Quote, submit, wait, save
pershot video takes the prompt in quotes. It asks for the price and prints it, submits the job, follows it to the end and saves the clip in the current folder. What it prints on standard output is the path of the file.
# Prints the price, submits, waits, then the path of the saved .mp4 pershot video "A paper boat on a rain puddle" -m mini -d 8 -r 480p -a 9:16 # The price only; nothing is submitted pershot video "A paper boat on a rain puddle" --dry-run # Refuse anything over 100 credits pershot video "A paper boat on a rain puddle" --max-credits 100Without options: Seedance 2.0 Fast, 5 seconds, 720p, 16:9, with audio. Options: -m fast or mini, -d 4 to 15 seconds, -r 480p or 720p, -a 16:9, 9:16 or 1:1, -i a first frame, --ref up to 9 reference images, --no-audio. Local images are uploaded first.
- 03 · Image
The same for images, or an edit
pershot image works the same way. Give it a picture with -i and it edits that picture instead of making a new one.
pershot image "A ceramic cup on a linen cloth, soft morning light" -s 2K # Edit a picture instead of making a new one pershot image "Make the background plain white" -i cup.pngWithout options: Fast, 1K, 1:1. Options: -m fast or mini, -s 1K or 2K, -a 16:9, 9:16 or 1:1. Pictures can be PNG, JPEG or WebP files, or https links.
- 04 · For agents
One reference, read once
pershot help --llms prints the full reference as one text written for AI agents: every command and option, the JSON each one returns and what each exit code means. Add --json to any command for a single JSON object on standard output.
# The whole reference, written for agents: read it once pershot help --llms # One JSON object on standard output, no progress lines pershot video "A paper boat on a rain puddle" --json --quiet echo $? # the exit code: 0 done, 4 not enough credits, 9 stopped waitingWith --json, errors are JSON too, on standard error, and the exit code says what kind of problem it was.
Made forunattended runs
- Price first
- Every job is quoted before it is submitted, and the price is printed. --dry-run prints the price and stops there.
- A ceiling per command
- --max-credits refuses anything that costs more, before anything is uploaded or submitted.
- Safe retries
- Every job is sent with an idempotency key. Give your own with --idempotency-key, and running the command again returns the same job instead of charging twice.
- Long jobs
- --no-wait prints the job id and returns at once. If the tool stops waiting, the job carries on, and you can wait for it again later (exit code 9 below).
- Its own sign-in
- The saved sign-in is only ever sent to the server it was made for. To bill the developer API balance instead, set PERSHOT_API_KEY to a developer API key (by application); it takes the place of the saved sign-in.
- Clean output
- Results go to standard output; progress and problems go to standard error. --quiet leaves out the progress lines.
Exit codesthat keep their meaning
Scripts and agents can branch on the exit code. Each code means the same thing in every version of the tool.
| Code | Meaning | What to do |
|---|---|---|
0 | Done | Read the result on standard output |
1 | Something unexpected | Read the message on standard error |
2 | The command line is wrong | Fix it. Every option is in the help: pershot help |
3 | Not signed in, or the sign-in or key was refused | Sign in: pershot login |
4 | Not enough credits | Top up, then run it again |
5 | The key may not do this: a permission, a model or a region | Use a key that is allowed to |
6 | Refused: an invalid request, over --max-credits, a price that changed, or content that is not allowed | Change the request |
7 | Busy: the rate limit or the concurrency limit | Wait, then try again |
8 | The job failed or was canceled | Read why. The job shows what it cost, if anything: pershot job <id> |
9 | Stopped waiting. The job continues | Wait for it again: pershot job <id> --wait |
10 | The service could not be reached, or answered with a server error | Try again later with the same --idempotency-key |
11 | Waiting for a person. The samples ran first; the rest wait until someone approves them on the web | Ask them to review at the link it printed, then wait for the batch: pershot batch wait <id> |
Command-linequestions
When can I install it?
Not yet: the tool is not published, and real renders are not open yet. Leave your email on a model page and we write once, when they open.
Do I paste an API key into it?
No. pershot login shows a link and a code; you allow it in your browser and the tool receives a sign-in of its own, which spends your creative balance. A developer API key in PERSHOT_API_KEY (by application) also works and bills the developer API balance instead.
Where does it keep its sign-in?
In ~/.config/pershot/credentials.json by default, readable by your user only. pershot logout deletes that file. The sign-in itself stays under AI connections until you revoke it there, or until it ends after 90 days.
How does an AI agent learn to use it?
Have it run pershot help --llms once. The reference covers every command, option, output and exit code, so the agent does not have to guess.
Does the tool cost extra?
No. Signed in, it spends your creative balance at the same prices as the studio.