# blender.farm > Cloud render farm for Blender. Each render runs on its own RTX 5090 machine (up to four when split). Billed only while Blender renders: 1 credit = 20 minutes of one GPU, charged in 5-minute blocks of 0.25 credits. Scripts and AI agents can render in two ways: the Blender add-on's command line (easiest, when Blender is installed) or a JSON HTTP API with a personal API key. ## Which way to use Before any render, tell the person what it will cost and ask before starting it. The dry run (`--dry-run`) is free and gives an estimate; it can be off. A test render is optional: offer one (`--test`, or `"test": true` in the API; usually 0.25 credits) when the person wants a firmer cost or to see the frames first, and skip it when they do not. - Blender is installed on this computer: use the add-on's command line. Blender opens the .blend, so the add-on finds every texture, library, cache and add-on the scene needs and uploads them. You only pass the file. - No Blender here (a server, a pipeline): use the HTTP API. It does not read the .blend, so you send a packed .blend or list its external files yourself. ## Command line (Blender add-on, Blender 4.2 and newer) Guide: https://www.blender.farm/guide/addon-command-line. Every command: `blender -c blender_farm help` and `blender -c blender_farm COMMAND --help`. - Install or update, once, when `blender -c blender_farm help` fails or does not list `login` (it needs add-on 1.33.0 or newer): download https://www.blender.farm/downloads/blender_farm.zip, then run `blender -b --python-expr "import bpy; bpy.ops.preferences.addon_install(filepath=r'/full/path/to/blender_farm.zip', overwrite=True); bpy.ops.preferences.addon_enable(module='blender_farm'); bpy.ops.wm.save_userpref()"`. Do not add --factory-startup: it would save factory settings over the person's own preferences. - Sign in, once: `blender -c blender_farm login --json`. It prints a link on stderr; give it to the person, who opens it in a browser where they are signed in to blender.farm (any device) and clicks Allow. The command then exits 0. Exit 3 from any command means: sign in this way. A sign-in from the add-on panel counts too. - Check first, free: `blender -c blender_farm submit shot.blend --dry-run --json` runs every check and reports scenes, frames, files found and missing, the cost estimate and the credits needed. Nothing is saved, uploaded or charged. Exit 0 means the real run would launch; 5 means it needs --yes, 8 not enough credits, 6 refused (reason in error.message). - Optional test: `blender -c blender_farm submit shot.blend --test --wait --json`: up to 5 frames per scene as PNG on one GPU, usually 0.25 credits. Only when the person wants one. - Render: `blender -c blender_farm submit shot.blend --wait --json`. Every option is optional; without any, the scene the file opens on renders with the file's own settings. Options (for every rendered scene, applied on the render machine; the .blend keeps its own settings): `--frames 1-250` or `--frames 7`, `--step 2`, `--scenes A B` or `--all-scenes`, `--format PNG|JPEG|OPEN_EXR|FFMPEG|...`, `--resolution 1920x1080`, `--percent 50`, `--samples 128` (Cycles or Eevee), `--camera NAME` (a camera object in the scene), `--gpus 2` (split across up to 4 GPUs), `--ignore-missing`, `--yes` (accept the 1-credit extra-machine fee and the split note; without it the command stops with exit 5 and says what it would cost). - Follow: `blender -c blender_farm status [ID] --wait --json`, `blender -c blender_farm list --json`. - Download: `blender -c blender_farm download [ID] --to DIR --json` (without ID: the latest render; add --wait to wait for it to finish first). Frames, the movie and compositor File Output files; files already there at the right size are skipped, so running it again fetches only what is missing. - `--json`: exactly one line of JSON on stdout, the line starting with `{`; progress, warnings, logs and the login link go to stderr. - Exit codes: 0 done, 1 unexpected error, 2 bad arguments, 3 not signed in, 4 add-on or Blender too old, 5 needs --yes, 6 refused before launch (reason printed), 7 network, upload or download failed, 8 not enough credits, 9 (--wait) the render failed or was stopped, 10 no such render, 130 interrupted (the render carries on). ## HTTP API (for scripts and AI agents) Full reference, examples and a curl walkthrough: https://www.blender.farm/guide/api - Base URL: https://dashboard.blender.farm/api/v1 - Auth: header `Authorization: Bearer bf_live_...`. If you have no key, ask the person to create one on the Render with AI page of the dashboard, https://dashboard.blender.farm/developers, and give it to you. Never put a key in a URL; such requests are refused. - The API is for accounts that have bought credits: every request, and creating a key, needs one completed credit purchase on the account (403 api_requires_purchase otherwise). - Flow: POST /renders (describe the .blend and any external files) -> PUT each file's bytes to its returned upload url (no auth header) -> POST /renders/{id}/launch -> poll GET /renders/{id} until status is completed, failed or destroyed -> GET /renders/{id}/outputs and download each file's url. - The API does not read the .blend: send a packed .blend (File > External Data > Pack Resources), or list each external file in `dependencies` with its kind and its path as the .blend stores it. Simulation bake folders and UDIM tiles need the Blender add-on. - Launch body: `render` with blenderVersion ("4.5"), frameStart, frameEnd, resolutionX, resolutionY (required) and frameStep, resolutionPercent, outputFormat (PNG default; JPEG, WEBP, BMP, TIFF, OPEN_EXR, OPEN_EXR_MULTILAYER, FFMPEG), scene (optional). `"test": true` renders up to 5 frames per scene first, at full size, as PNG, on one GPU. - Errors: JSON `{ "error": "", "message": "" }`. 402 insufficient_credits, 403 api_requires_purchase, 409 wrong_status / inputs_missing, 429 rate_limited (honour Retry-After). - Limits: 120 requests and 20 writes per minute per key, 240 and 40 for all of an account's keys together; 5 GB per uploaded file; 5000 frames per render; everything kept 30 days. ## Endpoints - GET /account: balance, whether the account can create renders, the extra-machine fee, this key's limits - GET /renders: renders of the last 30 days with status, progress and credits charged - POST /renders: create a render, returns one upload url per file - GET /renders/{id}: status, progress, cost so far, estimate of the rest, failure reason - POST /renders/{id}/launch: start, test or relaunch - POST /renders/{id}/stop: stop the machine; billing ends - GET /renders/{id}/outputs: every output file with a download url (valid 12 hours) ## Other docs - User guide: https://www.blender.farm/guide - Credits and billing: https://www.blender.farm/guide/credits-and-billing - Limits and retention: https://www.blender.farm/guide/limits - Pricing: https://www.blender.farm/pricing