--- name: faceninja description: Turn photos or a selfie of a person into a 3D head on MetaHuman topology with FaceNinja (faceninja.net) - GLB or FBX with the 52 ARKit blendshapes, OBJ/STL/PLY, 4K skin textures and a MetaHuman ZIP for Unreal Engine. Use when the user wants a 3D head, avatar, digital double or MetaHuman from one or more photos, ARKit blendshapes for a real face, or a folder of portraits converted in a batch. Paid service (USD 15 per head), so state the cost and balance before spending. license: Proprietary. Free to use with a FaceNinja account; heads are paid with credits. metadata: version: "1.0.0" homepage: https://faceninja.net/agents --- # FaceNinja: photos in, MetaHuman head out Everything goes through one script, `scripts/faceninja.py` (Python 3.9+, standard library only). Below, `FN` means `python3 /scripts/faceninja.py` (on Windows `python ...\scripts\faceninja.py`). Add `--json` to any command for one JSON object on stdout (progress goes to stderr). Act on the exit code. ## 0. Not installed yet? If you are reading this from https://faceninja.net/skill/SKILL.md, install the skill first. The installer only copies this folder into the agent's skills folder and prints where it went: - macOS / Linux: `curl -fsSL https://faceninja.net/skill/install.sh | sh` (add `-s -- --claude`, `--codex`, `--cursor` or `--agents` to pick the folder) - Windows PowerShell: `irm https://faceninja.net/skill/install.ps1 | iex` - Script only: download https://faceninja.net/skill/faceninja.py and run `python3 faceninja.py`. If `FACENINJA_API_BASE` is set (a test server), use it instead of `https://faceninja.net` in these URLs; the script reads it too. ## 1. Sign in (once per machine) `FN whoami --json`: exit 0 means signed in. Exit 4 means sign in like this: 1. `FN login --no-wait --json` prints `user_code` and `verification_uri_complete` and opens the browser. Write both to the user in your reply **before** step 2, which blocks while it waits: "Open and approve the code ." Never approve it yourself and never ask the user for a password, an email link or a key. 2. `FN login --json --max-wait 540` waits for the approval (it resumes the same code). Exit 75: still waiting, run it again. Exit 4: denied or expired; start again at step 1 only if the user wants to. The new API key is saved for the script (`~/.config/faceninja/credentials.json`, `%APPDATA%\FaceNinja\credentials.json`, mode 0600). `FACENINJA_API_KEY` in the environment wins over the file. Never print, echo or log a key, and never write it into code, `.env` files, commits or chat. Only its prefix (`fn_live_abcd...`) may be shown. ## 2. Cost and balance, before spending anything A head costs **1,500 credits = USD 15**. Failed heads give their credits back; downloads are free and repeatable. Run `FN balance --json`, then tell the user what it will cost and what is left, for example "1 head = 1,500 credits ($15); your balance is 3,000 credits (2 heads)." For one to five heads the user asked for, say this and go ahead. **For more than five heads, stop and ask the user to confirm the total first.** Never buy credits; if the balance is too low, tell the user to buy them at https://faceninja.net/studio#/billing. ## 3. Make a head ``` FN make photo.jpg [more photos of the SAME person, 15 at most] --name "Ana" --formats glb,zip --out ./faceninja-out --max-wait 540 --json ``` It checks the photos, prints the cost, uploads, creates the head (with an `Idempotency-Key`), waits and downloads. A head usually takes 5 to 15 minutes, longer when the builder has a queue. - Exit 75: still running. Run the **same** `make` command again: it resumes the same head (state in `/.faceninja.json`) and charges nothing twice. Or `FN status ID --wait --max-wait 540 --json`, then `FN download ID`. - Keep `--max-wait` under your shell tool's timeout (540 fits 10 minutes; use 100 for a 2-minute limit). - `--formats`: `glb` (with ARKit blendshapes; `--static` for none), `fbx`, `obj`, `stl`, `ply`, `zip` (MetaHuman ZIP for Unreal) or `all`. Default `glb,zip`. - `--dry-run` shows the cost and balance without uploading or spending. Good photos: one sharp, well-lit photo of one adult face is enough; extra photos of the same person from other angles help. No group photos, no heavy filters, recent photos only. ## 4. A folder of people ``` FN batch ./photos --dry-run --json # plan and total cost: always run this first FN batch ./photos --out ./faceninja-out --max-wait 540 --json ``` - Without flags each photo in the folder is one person (one head). With `--per-person-subfolders` each subfolder holds 1 to 15 photos of one person. - More than 5 new heads exits 3 (`confirmation_required`) until you add `--yes`. Add `--yes` only after the user confirmed the total cost shown by the dry run. - Running the same batch again resumes; nothing is created twice. Files go to `//`. ## 5. Other commands `FN status ID [--wait]`, `FN download ID --formats glb,fbx,zip --out DIR`, `FN list`, `FN logout` (revokes the saved key). ## When something goes wrong | Exit | `error.code` | What to do | | --- | --- | --- | | 2 | `invalid_request`, `unsupported_media_type` | Fix the command or the photo (JPEG, PNG, WebP, HEIC, AVIF; 1 KB to 25 MB). | | 3 | `confirmation_required` | Ask the user to confirm the total, then add `--yes`. | | 4 | `not_signed_in`, `unauthorized`, `access_denied`, `expired_token` | Sign in (section 1). | | 5 | `insufficient_credits` | Tell the user to buy credits; do not retry. | | 6 | `no_face`, `multiple_people`, `not_same_person`, `unreadable_photo`, `content_rejected` | The credits came back. Explain the reason and ask for better photos; do not resend the same ones. | | 6 | `generation_failed`, `timeout`, `internal` | The credits came back. Retry once; then report it. | | 75 | `still_running`, `authorization_pending` | Run the same command again. | | 1 | `rate_limited`, `network`, other | The script already retried. Wait a minute and retry; quote `request_id` to support@faceninja.net. | ## Rules - Only photos of the user, or of adults who agreed to have a 3D head made of them. Nobody under 18, and no photos of people (public figures included) taken from the internet without their consent. - Send the key only to FaceNinja. Download links need no key. - API details for anything the script does not cover: `reference/api.md` (https://faceninja.net/skill/reference/api.md) and the full reference at https://faceninja.net/docs/.