fotoai

FotóAI from the command line — and for AI agents. Generate images, videos and speech with your fotoai.hu credits: the same models, the same prices and the same account as the website.

• Every generation is quoted first; you confirm the price (or pass --yes).
• --wait shows progress, --out <dir> downloads the results.
• --json for scripts and agents (the default when the output is piped).
• Ships an Agent Skill (SKILL.md) for Claude Code and other agents.
• No dependencies, Node.js 18+.

Docs (Hungarian): https://fotoai.hu/dokumentacio/cli · MCP: https://fotoai.hu/dokumentacio/mcp

The API, the MCP server and the CLI are part of the Pro plan.

Install

npx fotoai-cli --help          # run without installing
npm install -g fotoai-cli      # or install the `fotoai` command

Log in

fotoai login               # opens your browser; approve the FotóAI CLI
fotoai whoami

The browser login uses OAuth 2.1 with PKCE and a one-time listener on 127.0.0.1. Tokens are stored in ~/.config/fotoai/config.json (mode 0600) and refreshed automatically. fotoai logout forgets them and revokes the session (you can also disconnect it on fotoai.hu under Beállítások › Kapcsolt alkalmazások).

On a server, in CI, or over SSH, use a personal API key (https://fotoai.hu/beallitasok/api-kulcsok):

fotoai login --api-key-stdin < key.txt     # or: fotoai login --api-key fai_live_…
export FOTOAI_API_KEY=fai_live_…           # or only for this shell / job

fotoai login --no-browser prints the address instead of opening it; if you approve on another machine, paste the address you land on back into the terminal.

Examples

fotoai credits                                   # plan and balance
fotoai models image                              # models with their starting price
fotoai models show image.nano-banana-2           # parameters and the full price table

fotoai image "egy piros alma fehér háttéren" --dry-run          # only the price
fotoai image "egy piros alma fehér háttéren" -a 1:1 --out ./out # asks, then waits and downloads
fotoai image "make it winter" --ref photo.jpg -m image.nano-banana-2 -y --out .
fotoai image "at a Budapest café" --character Anna --dry-run    # a saved character
fotoai image --style vinted-fotok --ref item.jpg --dry-run      # a pack: N images

fotoai video "slow dolly shot of a lake at dawn" -d 5 -y        # returns the job id
fotoai video "she turns and smiles" --start portrait.jpg -d 5 -y --out ./clips
fotoai tts "Szia! Ez a FotóAI hangja." -y --out ./audio

fotoai jobs list
fotoai jobs get <id> --wait --out ./out
fotoai jobs cancel <id>                         # only before rendering starts
fotoai assets list --kind image --limit 5
fotoai assets download <id> --out ./dl
fotoai upload face.jpg                          # → asset id for --ref / --start
fotoai styles
fotoai characters

Run fotoai <command> --help for every flag. Common generation flags: -m/--model, -a/--aspect, -r/--resolution, -n/--batch, -d/--duration, --voice, --ref <file|asset-id> (repeatable), --start/--end, -s/--style, -c/--character, --param key=value, --dry-run, -y/--yes, --wait/--no-wait, -o/--out <dir>, --timeout <s>.

Credits and confirmation

fotoai image|video|tts always asks the server for a quote first and shows it. On a terminal it asks Spend N credits? [y/N]. When the output is not a terminal (scripts, agents) it refuses to spend without --yes (CONFIRMATION_REQUIRED, exit code 2). The generation is sent with the quote id, so the server never charges more than the price you saw. Failed jobs are not charged.

JSON mode

fotoai image "a cat" --yes --json | jq -r '.outputs[0].url'
fotoai credits --json | jq .balance_credits

Data goes to stdout; progress and errors go to stderr. Errors look like {"error":{"code":"INSUFFICIENT_CREDITS","message":"…","hint":"Top up: …"}}.

| Exit code | Meaning | | --- | --- | | 0 | ok | | 1 | error (network, not found, provider) | | 2 | usage / validation / confirmation needed | | 3 | not logged in, or the login expired | | 4 | not enough credits, or a plan / tier gate | | 5 | rate limited | | 6 | the job failed or was rejected |

Agent skill (Claude Code and others)

The package ships SKILL.md, which teaches an AI agent to use FotóAI safely: log in, choose models by price, quote before spending, never loop generations without the user's OK, wait and download, parse JSON.

npx fotoai-cli skill install            # → ~/.claude/skills/fotoai/SKILL.md
npx fotoai-cli skill install --project  # → ./.claude/skills/fotoai/SKILL.md
npx fotoai-cli skill show               # print it (or --path)

MCP

The same account is also an MCP server (one server, two login methods: an API key or OAuth): https://fotoai.hu/api/mcp (Streamable HTTP).

claude mcp add --transport http fotoai https://fotoai.hu/api/mcp \
  --header "Authorization: Bearer fai_live_…"
fotoai mcp tools                                  # the server's tools
fotoai mcp call list_models '{"category":"video"}'

Configuration

| | | | --- | --- | | FOTOAI_API_KEY | API key; wins over the saved login | | FOTOAI_API_URL / --api-url | another FotóAI server (default https://fotoai.hu) | | FOTOAI_CONFIG_DIR | config directory (default ~/.config/fotoai, or $XDG_CONFIG_HOME/fotoai) | | NO_COLOR | no colors |

A saved login is only sent to the server it was created for.

License

MIT © 2026 Kiss Industries