HTTP API for scripts and AI agents
Create, launch, watch, stop and download renders over plain HTTP with a personal API key: every endpoint, a curl walkthrough, errors, limits and costs.
The API does over HTTP what the dashboard does: create a render from a .blend, upload it, launch it (or a cheap test of it), watch its progress and cost, stop it, and download what it made. It is meant for scripts, render pipelines and AI agents that work without a person at the screen. Everything is JSON under https://dashboard.blender.farm/api/v1.
- A key per script. Create one on the API page of the dashboard (Render with AI in the sidebar). You can hold 5 at a time and revoke any of them there. Resetting your password revokes all of them.
- For accounts that have bought credits. The API, and creating a key, unlock after your first credit purchase on any pack, the same rule as the browser uploader. Until then, render with the free Blender add-on.
- Times are milliseconds since 1970 (UTC). Credits are numbers in credits, in steps of 0.25.
- Blender installed where your script runs? The add-on's command line is simpler:
blender -c blender_farm submit shot.blendfinds every file a scene needs by asking Blender, which this API cannot do, and needs no key. See what the .blend needs to contain for the API.
Authentication
Send the key in the Authorization header of every request to the API. Nothing else is needed: no cookie, no login.
Authorization: Bearer bf_live_<the rest of your key>
- Shown once. The dashboard shows a new key one time. We keep only a hash of it, so a lost key cannot be shown again: revoke it and create another.
- Never in a URL. A request with a key anywhere in its address is refused with
api_key_in_url, because addresses end up in logs and browser history. If that happens, revoke the key. - Renders only. A key acts as your account for renders: it cannot buy credits, change account settings, or create and revoke keys. Those need you, signed in, in the dashboard.
- Treat it like a password. Keep it in an environment variable or a secret store, not in code you commit.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /account | Balance, whether this account can create renders, the extra machine fee, this key's limits |
| GET | /renders | Every render of the last 30 days, newest first, with status, progress and cost |
| POST | /renders | Create a render: returns an upload link per file |
| GET | /renders/{id} | Status, progress, cost so far, an estimate of the rest, the failure if any |
| POST | /renders/{id}/launch | Start it, a test of it, or relaunch it |
| POST | /renders/{id}/stop | Stop it; the machine is shut down and billing ends |
| GET | /renders/{id}/outputs | Every file it made, each with a download link |
Create a render
POST /renders describes the files; nothing is uploaded yet. blend is the scene file: its name and its size in bytes. blenderVersion is the version it was saved with, and is checked here, before you upload, rather than at launch. dependencies lists the files the .blend points at but does not contain (next section).
{
"blend": {
"name": "shot_010.blend",
"size": 48213421
},
"dependencies": [
{
"kind": "image",
"path": "//textures/wood_diffuse.png",
"name": "wood_diffuse.png",
"size": 1048576
},
{
"kind": "volume",
"path": "//cache/smoke_####.vdb",
"files": [
{
"name": "smoke_0001.vdb",
"size": 2097152,
"hash": "dee37aa176485cde38e9b03370a04ffc9b6313bfc67ffcf4423067281b1640cb"
},
{
"name": "smoke_0002.vdb",
"size": 2101248
}
]
}
],
"blenderVersion": "4.5"
}The answer carries the render's id and one entry per file, in the order you sent them, each with its own upload url. hash is optional on any file: the file's BLAKE2b-256 in lowercase hex (b2sum -l 256 file). When we already hold that file from one of your earlier renders, its entry says cached: true with no url, and there is nothing to upload.
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"status": "awaiting_upload",
"uploads": [
{
"name": "shot_010.blend",
"kind": "blend",
"method": "PUT",
"url": "https://…signed link…",
"cached": false
},
{
"name": "wood_diffuse.png",
"kind": "dependency",
"path": "//textures/wood_diffuse.png",
"method": "PUT",
"url": "https://…signed link…",
"cached": false
},
{
"name": "smoke_0001.vdb",
"kind": "dependency",
"path": "//cache/smoke_####.vdb",
"method": "PUT",
"url": null,
"cached": true
},
{
"name": "smoke_0002.vdb",
"kind": "dependency",
"path": "//cache/smoke_####.vdb",
"method": "PUT",
"url": "https://…signed link…",
"cached": false
}
],
"uploadUrlsExpireAt": 1763733600000,
"dashboardUrl": "https://dashboard.blender.farm/?jobId=3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01"
}What the .blend needs to contain
The dashboard reads your .blend in the browser to find its textures, and the add-on asks Blender. The API reads nothing from your file: the render machine opens exactly what you send, and anything the scene points at that you did not send renders missing (usually pink) without the render failing. So send one of these:
- 1A packed .blend (simplest)Pack every external file into the scene before you upload it: File > External Data > Pack Resources in Blender, or
bpy.ops.file.pack_all()followed by a save in a script. Thendependenciesis empty. - 2Or the .blend plus its filesList each file the scene points at in
dependencies:kind(image,library,sound,font,movieclip,cachefilefor Alembic or USD,volumefor OpenVDB),pathexactly as the.blendstores it (//textures/wood.pngfor a relative path), and the file'snameandsize. Adddatablock(the image's or volume's name in Blender) when two files share a file name. The machine matches the datablock name when you send one, then the stored path, then the file name. - 3Sequences are one entryA VDB, image or cache sequence is one entry with
files: every frame'snameandsize, names exactly as on disk.pathis the datablock's path, either one frame's or the####pattern. These cannot be packed, so they always go this way.
"test": true) shows within minutes whether everything arrived.Upload the files
PUT each file's bytes to its url, with no Authorization header: the link is the permission. The links are valid for 6 hours and take up to 5 GB per file; bigger files go through the Blender add-on, which uploads in parts. A failed PUT can simply be repeated. The launch checks that every file arrived and refuses with inputs_missing, naming them, if one did not.
jq -r '.uploads[] | select(.url != null) | [.name, .url] | @tsv' create.json \
| while IFS=$'\t' read -r NAME URL; do
curl -sS --fail -X PUT --upload-file "files/$NAME" "$URL"
doneLaunch
POST /renders/{id}/launch rents a machine and starts the render. It answers once a machine is rented, which usually takes seconds and can take a few minutes, so give it a client timeout of 5 minutes. If your client gives up sooner, read the render's status before launching again: a second launch while the first is still going is refused with launch_in_progress.
{
"render": {
"blenderVersion": "4.5",
"frameStart": 1,
"frameEnd": 250,
"frameStep": 1,
"resolutionX": 1920,
"resolutionY": 1080,
"resolutionPercent": 100,
"engine": "CYCLES",
"outputFormat": "PNG",
"scene": "Scene"
},
"test": false
}| render field | Required | What it does |
|---|---|---|
blenderVersion | yes | The version the file was saved with, like "4.5". Picks the Blender the machine renders with. |
frameStart, frameEnd | yes | The frames to render. A still is the same number twice. These replace the file's own range. |
frameStep | no, 1 | Every Nth frame. |
resolutionX, resolutionY | yes | The file's resolution in pixels, before the percentage. Used to size the machine's disk and to refuse a video size the codec cannot encode before anything is charged. |
resolutionPercent | no, 100 | 1 to 500. Replaces the file's own percentage. |
outputFormat | no, PNG | PNG, JPEG, WEBP, BMP, TIFF, OPEN_EXR, OPEN_EXR_MULTILAYER or FFMPEG for a video. Obeyed even if the file is set to something else. |
scene | no | The scene to render, by name. Left out: the scene the file opens on. |
engine | no, CYCLES | Recorded with the render; the engine actually used is the one saved in the file. |
Everything else (samples, camera, lights, colour management, the compositor) comes from the file. "test": true renders up to 5 frames spread over the range, at full size, as PNG, on one GPU: enough to check framing, materials and missing files for the cost of a block or two. The answer:
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"status": "starting",
"test": false,
"dashboardUrl": "https://dashboard.blender.farm/?jobId=3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01"
}A launch refused for lack of credits keeps its settings on the render, so after a top-up a launch with an empty body ({}) starts it as asked.
Relaunch a render
A render that is completed, failed or destroyed can be launched again. It reuses the first launch's settings; render may change only frameStart, frameEnd, resolutionPercent and outputFormat. Frames an earlier run already rendered with the same settings are kept and not charged again, unless you send "rerenderAll": true. After a test, "full": true renders the full settings the test was taken from; without it, relaunching a test runs the test again.
{
"render": {
"frameStart": 100,
"frameEnd": 250
},
"full": true
}Status, progress and cost
GET /renders/{id} is the render as the dashboard's job page sees it. Polling every 15 to 60 seconds is plenty. Nothing depends on you polling: the farm runs, bills and finishes the render either way.
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"name": "shot_010.blend",
"status": "rendering",
"test": false,
"client": "api",
"gpus": 1,
"createdAt": 1763712000000,
"launchedAt": 1763712120000,
"finishedAt": null,
"elapsedMs": 1260000,
"progress": {
"framesDone": 40,
"framesTotal": 250,
"etaMs": 3780000,
"etaLowMs": 3213000,
"etaHighMs": 5292000
},
"cost": {
"creditsThisRun": 1.25,
"machineFee": 0,
"billing": "running"
},
"estimate": {
"msRemaining": 3780000,
"msRemainingLow": 3213000,
"msRemainingHigh": 5292000,
"creditsRemaining": 3,
"creditsAtFinish": 4.25,
"creditsAtFinishLow": 3.75,
"creditsAtFinishHigh": 5.5
},
"balance": 41.25,
"failure": null,
"issues": null,
"render": {
"blenderVersion": "4.5",
"frameStart": 1,
"frameEnd": 250,
"frameStep": 1,
"resolutionX": 1920,
"resolutionY": 1080,
"resolutionPercent": 100,
"engine": "CYCLES",
"outputFormat": "PNG",
"scene": "Scene"
},
"fullRender": null,
"inputs": [
{
"name": "shot_010.blend",
"kind": "blend",
"size": 48213421,
"uploaded": true
},
{
"name": "wood_diffuse.png",
"kind": "dependency",
"size": 1048576,
"uploaded": true
}
],
"outputs": {
"framesReady": 40,
"videos": 0,
"extras": 0
},
"dashboardUrl": "https://dashboard.blender.farm/?jobId=3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01"
}| status | Meaning |
|---|---|
awaiting_upload | Created; waiting for its files and a launch. (ready means the same.) |
launching | A machine is being rented. |
starting | The machine is booting. |
preparing | Your files are downloading onto it and add-ons installing. Not billed. |
rendering | Blender is rendering. Billed. |
completed | Done. Check issues: a render can finish with a few frames missing. |
failed | Stopped by a problem; failure says which, in words, with a stable code. |
destroyed | Stopped, from the API or the dashboard. |
progressis null until the machine reports its frame count.etaMsis null until a frame has been timed;etaLowMsandetaHighMsare the range around it, which is wide after one frame and narrows from the second.cost.creditsThisRunis what the current run has cost so far; a relaunch starts a new run.creditsChargedin the list is every run together.cost.billingisnot_started,runningorfinished.estimateis the time left at this render's own pace (its frames after the first, which takes longer), and what the run will have cost by then in 5 minute blocks, with the range of each. An estimate, not a quote: null until there is a timed frame.failureandissuesare null while all is well. When set they look like this:
"failure": {
"code": "out_of_credits",
"title": "Out of credits",
"detail": "Your credit balance ran out, so the render was stopped. Frames rendered before that are kept for 30 days. Top up to continue. Relaunch to finish it: the frames already rendered are kept, and only the missing ones are rendered and charged."
}
"issues": {
"missingFrames": [
{
"frame": 118,
"scene": null
}
],
"hint": "Blender crashed on these frames. Relaunch to try them again: only the missing frames are rendered and charged."
}Download the results
GET /renders/{id}/outputs lists every file the render has made so far, with a download link each: frame files, a video per scene that rendered one, and extra files from compositor File Output nodes. It works while the render runs, so you can fetch frames as they arrive. Links last 12 hours; ask again for fresh ones. logUrl is the machine's render log once it has finished. Everything is kept for 30 days.
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"status": "completed",
"done": true,
"files": [
{
"type": "frame",
"name": "frame_0001.png",
"frame": 1,
"scene": null,
"size": 3145728,
"url": "https://…signed link…"
},
{
"type": "frame",
"name": "frame_0002.png",
"frame": 2,
"scene": null,
"size": 3149201,
"url": "https://…signed link…"
},
{
"type": "extra",
"name": "passes/depth_0001.exr",
"frame": null,
"scene": null,
"size": 8388608,
"url": "https://…signed link…"
}
],
"framesPending": 0,
"logUrl": "https://…signed link…",
"urlsExpireAt": 1763755200000
}Stop a render
POST /renders/{id}/stop shuts the machine down. Billing ends with the block in progress and frames already rendered are kept. Stopped before it began rendering, the credit held for its launch comes back. A render that is already over answers 409 not_running.
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"status": "destroyed",
"note": null
}List renders and read the balance
{
"renders": [
{
"id": "3f6c2a1e-8d4b-4c1a-9e7f-2b5d6a8c9e01",
"name": "shot_010.blend",
"status": "rendering",
"test": false,
"client": "api",
"gpus": 1,
"createdAt": 1763712000000,
"creditsCharged": 1.25,
"progress": {
"framesDone": 40,
"framesTotal": 250,
"etaMs": 3780000,
"etaLowMs": 3213000,
"etaHighMs": 5292000
},
"failure": null
}
],
"balance": 41.25
}{
"account": {
"id": "9b1c4e2a-5f3d-4a7b-8c6e-1d2f3a4b5c6d",
"balance": 41.25,
"hasPurchased": true,
"renderBlocked": false
},
"canCreateRenders": true,
"machineFee": {
"credits": 1,
"activeMachines": 0
},
"key": {
"name": "render pipeline",
"prefix": "bf_live_Ab3dE9"
},
"limits": {
"requestsPerMinute": 120,
"writesPerMinute": 20,
"accountRequestsPerMinute": 240,
"accountWritesPerMinute": 40
}
}A complete walkthrough with curl
Create, upload, launch, poll, download, for a packed .blend (uses curl and jq):
export BF_KEY="bf_live_..." # dashboard.blender.farm/developers
API=https://dashboard.blender.farm/api/v1
AUTH="Authorization: Bearer $BF_KEY"
# 1. Create the render: one packed .blend, nothing else to send.
SIZE=$(wc -c < shot_010.blend | tr -d ' ')
curl -sS --fail-with-body -X POST "$API/renders" -H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"blend":{"name":"shot_010.blend","size":'"$SIZE"'},"blenderVersion":"4.5"}' \
> create.json
ID=$(jq -r '.id' create.json)
# 2. Upload: PUT the file to its own link. No Authorization header here.
# A file with "cached": true is already stored and has no link.
URL=$(jq -r '.uploads[0].url' create.json)
[ "$URL" != "null" ] && curl -sS --fail -X PUT --upload-file shot_010.blend "$URL"
# 3. Launch. Add "test": true for a five-frame check at full size first.
curl -sS --fail-with-body -X POST "$API/renders/$ID/launch" -H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"render":{"blenderVersion":"4.5","frameStart":1,"frameEnd":250,"resolutionX":1920,"resolutionY":1080}}'
# 4. Poll until it is over.
while :; do
STATUS=$(curl -sS "$API/renders/$ID" -H "$AUTH" | jq -r '.status')
echo "$(date +%T) $STATUS"
case "$STATUS" in completed|failed|destroyed) break ;; esac
sleep 30
done
# 5. Download every file it made.
curl -sS "$API/renders/$ID/outputs" -H "$AUTH" \
| jq -r '.files[] | [.name, .url] | @tsv' \
| while IFS=$'\t' read -r NAME URL; do
mkdir -p "out/$(dirname "$NAME")"
curl -sS --fail -o "out/$NAME" "$URL"
doneErrors
Anything but a 2xx answers with a stable error code to branch on and a message written for a person, sometimes with a detail such as your balance:
{
"error": "insufficient_credits",
"message": "You need at least 1 credit to start a new render. Top up before launching.",
"balance": 0.5
}| HTTP | error | What to do |
|---|---|---|
| 400 | invalid_request, invalid_json, video_odd_size | Fix the request; message says what is wrong. |
| 400 | unsupported_blender_version | Save the file in a supported version and send that. |
| 400 | render_field_fixed | A relaunch tried to change a setting only a new render can. |
| 400 | api_key_in_url | Move the key to the header, and revoke it. |
| 401 | api_key_required, api_key_invalid, api_key_revoked | Send a current key as Authorization: Bearer .... |
| 402 | insufficient_credits | Top up. A launch needs at least 1 credit (2 while another render of yours is running). |
| 403 | api_requires_purchase | Buy any credit pack once: the API is for accounts that have. |
| 403 | render_blocked, account_suspended | Rendering is paused on the account. Mail us. |
| 404 | not_found | No render with that id on your account. |
| 409 | wrong_status, launch_in_progress, not_running | The render is not in a state for that; read its status. |
| 409 | inputs_missing | A file never arrived; upload it again, then launch. |
| 409 | nothing_left_to_render | Every frame already exists with these settings; send rerenderAll to render them again. |
| 404, 405 | unknown_route, method_not_allowed | Check the path and method against the table above. |
| 413 | file_too_large | Over 5 GB in one file: use the Blender add-on. |
| 429 | rate_limited | Wait the Retry-After seconds. |
| 500, 503 | internal, unavailable | Our side. Try again; if it persists, mail contact.blenderfarm@gmail.com with the render id. |
| 502, 503 | maintenance, no_offer_available, create_instance_failed, launch_unavailable | No machine could be had just now, or we are mid-maintenance. Nothing was charged; launch again in a few minutes. |
Rate limits
Each key may make 120 requests a minute, of which 20 may be writes (creating, launching, stopping), and all of an account's keys together 240 requests a minute, of which 40 may be writes. Every answer to a valid key carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the minute starts over); over the limit the answer is 429 with Retry-After. Uploads and downloads go straight to storage and do not count.
What costs credits
- Rendering, and nothing else. 1 credit is 20 minutes of one RTX 5090, charged in 5 minute blocks of 0.25 credits while Blender renders. API calls, uploads, waiting for a machine, preparing and downloading are free.
- Starting needs 1 credit on your balance, held at launch and used for the first blocks; whatever the render does not use comes back.
- Several at once: each machine that starts rendering while another of yours is rendering costs 1 credit extra, the extra machine fee. A test render never pays it.
- Running out mid-render stops the machine at the end of the block already paid for; the frames are kept and a relaunch renders only the rest.
