Guide · Studio

The Brikk API

Drive Brikk from scripts, build pipelines, or AI agents. With a Studio personal access token you can generate models, add animations, create retextured variants, and download .bbmodel / Java / Bedrock / resource-pack files — everything lands in your Brikk library, exactly as if you built it in the studio.

1. Create a key

Go to Settings → API keys, name the key, pick its scopes, and generate it. The full key is shown once — copy it immediately and store it as a secret (an environment variable, never in code). You can hold up to 5 active keys and revoke any of them instantly.

brikk_pat_9f2c…   # brikk_pat_ + 64 hex characters

2. Authenticate

Send the key as a bearer token. Verify it (and see your balance and scopes) with the index endpoint:

curl https://brikk.lootvote.com/api/v1 \
  -H "Authorization: Bearer $BRIKK_API_TOKEN"

3. Limits & costs

Token spend comes out of your normal monthly allotment (plus any top-ups) and is refunded automatically when a generation fails. An empty balance returns 402.

4. Endpoints

5. Quick start (curl)

Generate a model, animate it, and download the Blockbench file. Generations can take 1–2 minutes — use a request timeout of at least 300 seconds.

BASE=https://brikk.lootvote.com/api/v1
AUTH="Authorization: Bearer $BRIKK_API_TOKEN"

# 1) Generate — capture the model id
ID=$(curl -s -X POST "$BASE/generate" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"prompt":"a mossy stone golem","category":"entity"}' | jq -r .id)

# 2) Animate it (clip is saved onto the model)
curl -s -X POST "$BASE/animate" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"modelId\":\"$ID\",\"animation\":\"a heavy walk cycle\"}" > /dev/null

# 3) Download the editable Blockbench project
curl -sL "$BASE/models/$ID/export?format=bbmodel" -H "$AUTH" -o golem.bbmodel

6. Quick start (TypeScript)

No SDK needed — it's plain fetch. (A ready-made client/CLI also ships in the repo at scripts/brikk-generate.ts.)

const BASE = "https://brikk.lootvote.com/api/v1"
const headers = {
  Authorization: `Bearer ${process.env.BRIKK_API_TOKEN}`,
  "Content-Type": "application/json",
}

// Generate
const gen = await fetch(`${BASE}/generate`, {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "a ruby greatsword", category: "weapon" }),
})
if (!gen.ok) throw new Error((await gen.json()).error)
const { id } = await gen.json()

// Retexture into a shadow variant (new model, original untouched)
await fetch(`${BASE}/retexture`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    modelId: id,
    instruction: "shadow variant, obsidian black with purple glow",
    variantDisplayName: "Shadow Greatsword",
  }),
})

// Export the .bbmodel
import { writeFile } from "node:fs/promises"
const file = await fetch(`${BASE}/models/${id}/export?format=bbmodel`, { headers })
await writeFile("ruby_greatsword.bbmodel", Buffer.from(await file.arrayBuffer()))

7. Quick start (Python)

import os, requests

BASE = "https://brikk.lootvote.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['BRIKK_API_TOKEN']}"}

r = requests.post(f"{BASE}/generate", headers=H, timeout=300,
                  json={"prompt": "a crystal battle axe", "category": "weapon"})
r.raise_for_status()
model_id = r.json()["id"]

export = requests.get(f"{BASE}/models/{model_id}/export",
                      headers=H, params={"format": "bbmodel"}, timeout=120)
open("crystal_axe.bbmodel", "wb").write(export.content)

8. Errors

Error bodies are always { "error": "message" }.

9. Keep your key safe

• A key acts as your account: it can spend your tokens and read your whole library.
• Pass it via environment variables; never commit it or ship it in client-side code.
• Give each integration its own key with only the scopes it needs.
• Brikk stores only a hash of the key — the raw value can't be recovered, only replaced. Revoke leaked keys immediately in Settings → API keys; revocation is instant.