phaya-cli

Command-line client for the Phaya Media API — generate images, video, music and speech, add Thai subtitles, download videos, and run LLM chat completions, all from your terminal.

npm install -g phaya-cli
phaya login <your_api_key>
phaya image "a serene mountain landscape at sunset" --ar 16:9
# → https://.../result.png

Every generation command creates an async job, polls it for you, and prints the result URL when it completes. Add --out file.png to download the result, --no-wait to just print the job id, or --json for the raw API response.

Requirements

• Node.js ≥ 18.17
• A Phaya API key (create one in your Phaya dashboard → API Keys)

Setup

phaya login <api_key>     # saved to ~/.config/phaya/config.json (0600)
phaya doctor              # verify connectivity + key
phaya credits             # check your balance
phaya update              # self-update to the latest version (--check to only report)

Configuration precedence: flags (--key, --base) → environment (PHAYA_API_KEY, PHAYA_BASE) → config file → default base https://api.phaya.io/api/v1.

Cost warning: every generation deducts real credits when the job is created. Credits are auto-refunded on failed/cancelled jobs. Expensive commands (Sora 2, Seedance, Kling, Veo) ask for confirmation in interactive terminals — skip with --yes.

Commands

Images

| Command | Model | Credits | |---|---|---| | phaya image "<prompt>" [--ar 16:9] | Z-Image | 1.0 | | phaya seedream "<prompt>" [--image url] [--quality high] | Seedream 5.0 | 1.5 | | phaya nano-banana "<prompt>" [--image url]... [--resolution 4K] | Nano Banana 2 | 2–4 |

Video

| Command | Model | Credits | |---|---|---| | phaya ken-burns --image <url> [--zoom pan_right] | FFmpeg Ken Burns | 0.5 | | phaya sora2 "<prompt>" [--image url] [--character id] | Sora 2 i2v | 8.0 | | phaya sora2-t2v "<prompt>" | Sora 2 t2v | 8.0 | | phaya sora2-character --video <url> ["<description>"] | Sora 2 character | 0.5 | | phaya seedance "<prompt>" [--resolution 1080p --duration 12 --audio] | Seedance 1.5 Pro | 2–35 | | phaya grok-video ["<prompt>"] [--image url] [--mode fun] [--duration 6-15] | Grok Imagine | 0.81/s | | phaya kling --image <url> --video <motion_url> ["<prompt>"] | Kling 2.6 Motion Control | 1.21–1.82/s | | phaya veo "<prompt>" [--model veo3] | Veo 3.1 | 15 / 50 |

Audio & speech

| Command | Model | Credits | |---|---|---| | phaya music "<prompt>" [--style "lofi hip hop"] [--instrumental] | Suno (2 tracks) | 3.0 | | phaya tts "<text>" [--voice Kore] [--language th] | Gemini TTS | token-based | | phaya voices | list TTS voices (no auth) | free |

Media utilities

| Command | Description | Credits | |---|---|---| | phaya subtitle --media <url> [--script "..."] | Thai subtitles (Whisper) | 0.17/min | | phaya download <url> [--format mp3] | yt-dlp download (server-side) | 0.5/10MB | | phaya media overlay-text --video <url> --text "..." | bold text overlay | 0.2 | | phaya media extract-last-frame --video <url> | last frame as image | 0.2 | | phaya media <op> --data '{...}' | merge-video, merge-audio-video, merge-audio, overlay-gif, transcribe | varies |

LLM & embeddings

phaya chat "explain quantum computing in one sentence"
phaya chat "translate to Thai: hello" --system "you are a translator" --temperature 0.2
echo "summarize this" | phaya chat            # reads stdin when no message given
phaya embed "some text to embed"
phaya models && phaya pricing

phaya chat prints the assistant reply directly (Phaya-GPT returns a flat message.content, not OpenAI choices[]). For OpenAI SDK drop-in compatibility, point the SDK at https://api.phaya.io/v1 with your Phaya key instead.

Jobs & account

phaya status <service> <job_id>   # service = any generation command, or "media"
phaya cancel <service> <job_id>   # sora2, sora2-t2v, sora2-character, seedance, grok-video, kling, veo
phaya history image --limit 10    # image | music | tts
phaya credits                     # balance
phaya credits-history --limit 20  # transactions
phaya profile                     # full profile
phaya characters                  # your Sora 2 characters
phaya platforms                   # video-download supported platforms

Escape hatch

Any endpoint not covered by a dedicated command:

phaya api GET /user/profile
phaya api POST /media/merge-video --data '{"video_urls": ["u1", "u2"]}'

Global flags

| Flag | Effect | |---|---| | --json | print the raw JSON response | | --no-wait | print the job_id immediately instead of polling | | --out <file> | download the result to a file | | --poll-interval <s> | seconds between status polls (default 4) | | --timeout <s> | max seconds to wait (default 600) | | --key <api_key> / --base <url> | per-call overrides | | --yes, -y | skip cost confirmation on expensive jobs | | --quiet | suppress progress messages on stderr |

Result URLs go to stdout; progress and job ids go to stderr — safe to pipe:

URL=$(phaya image "logo sketch" --quiet)
phaya tts "สวัสดีครับ" --language th --out hello.wav

Exit codes

| Code | Meaning | |---|---| | 0 | success | | 1 | API/job failure (job failed, network error, timeout) | | 2 | usage error (bad flag, missing argument) | | 3 | authentication error (401) | | 4 | insufficient credits (402) | | 5 | rate limited (429 — limit is 60 requests/minute per key) |

More docs

• docs/COMMANDS.md — full per-command flag reference
• docs/RECIPES.md — pipelines and scripting patterns
• phaya help <command> — the same reference, offline

License

MIT © Phaya