Studio Tank API and MCP

Account, plan and quota

Returns the plan, downloads used this month, random rolls left today, limits and the key in use.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Parts, options and clips catalog

Everything a recipe can use: the character's part ids per category, styles, color zones, palettes, clips, presets and export options. With `kind` (creature, critter, human, toon, tree, building, prop, vfx, world), that model kind's catalog: species, breeds with traits and default colors, the traits each species accepts, wardrobe, color zones and what each one paints, control ranges, clips and export options. Metadata only; names in the requested language.

• 200 OK (Catalog, or ModelCatalog with kind)
• 400 Unknown kind (invalid_kind).
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Validate a recipe

Normalizes the recipe (ids and colors checked), returns the short code and explains what was replaced, what was defaulted and what ends up hidden (e.g. a helmet hides hair). Free.

{
  "config": {
    "name": "Ana",
    "parts": {
      "helmet": "helm_wizard",
      "handR": "r_staff"
    },
    "palette": {
      "primary": "#5b3fc4"
    }
  }
}

• 200 OK
• 400 Neither config nor code, or an invalid code.
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Random characters

Generates 1 to 10 recipes consistent with a style (or any style). With `seed` the result is reproducible. On the free plan it counts toward the daily random limit.

{
  "style": "mago",
  "count": 2,
  "seed": 42
}

• 200 OK
• 400 Invalid style, count or seed.
• 401 Missing or invalid API key.
• 402 Daily random limit reached (free plan).
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Image preview

Server-rendered PNG portrait, 128 or 256 px. Does not use a download; limited per hour (free 30, Pro 300, shared with /models/preview).

{
  "config": {
    "name": "Bomber",
    "parts": {
      "head": "head_round",
      "hair": "hair_short",
      "eyes": "eyes_big",
      "mouth": "mouth_open",
      "beard": "beard_none",
      "helmet": "helm_bomber",
      "body": "body_bomber",
      "legs": "legs_cargo",
      "boots": "boots_sneakers",
      "gloves": "gloves_cartoon",
      "back": "back_bombs",
      "handR": "r_bomb",
      "handL": "l_none"
    },
    "palette": {
      "skin": "#f2c39b",
      "hair": "#5a3a22",
      "eyes": "#2fb3c4",
      "primary": "#f07f2a",
      "secondary": "#2f4f8f",
      "detail": "#f2c534",
      "metal": "#b9c2cf",
      "leather": "#5a3a22",
      "glow": "#ff6b3d",
      "dark": "#1d1b26",
      "white": "#f7f7fb",
      "tongue": "#e2697c",
      "flash": "#ffd24a",
      "fire": "#ff6a1a",
      "ice": "#8fe8ff",
      "venom": "#7ee83c",
      "bolt": "#ffe24d",
      "void": "#a052ff",
      "holy": "#fff0a8"
    }
  },
  "size": 256
}

• 200 PNG image
• 400 Invalid avatar or size.
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).
• 503 Render queue full.

Validate a model recipe

Normalizes a model recipe ({kind, recipe} or {kind, code}) with that kind's rules, the same as the studio and the export, and explains what changed: a field the kind does not have (unknown_field), an id outside the list (unknown_option), a breed or trait of another species (wrong_species), a piece of the other gender (wrong_gender), a number clamped to its range (adjusted), an invalid color (invalid_color), a zone the model does not paint (unused_zone) or keeps fixed (fixed_zone), dropped items (dropped). Returns the normalized recipe, its code (base64url JSON) and the clips the model has. Free.

Cartoon doberman (critter) with a mistake

{
  "kind": "critter",
  "recipe": {
    "kind": "critter",
    "name": "Thor",
    "species": "dog",
    "breed": "doberman",
    "traits": {
      "ears": "floppy",
      "wings": "big"
    },
    "size": "medium",
    "palette": {
      "glow": "#ff0000"
    }
  }
}

Low poly husky (creature)

{
  "kind": "creature",
  "recipe": {
    "kind": "creature",
    "name": "Nevasca",
    "species": "dog",
    "breed": "husky",
    "eyes": "happy",
    "neck": "scarf",
    "size": "medium",
    "finish": "lowpoly",
    "palette": {
      "skin": "#d63a3a"
    }
  }
}

Cartoon dalmatian (critter)

{
  "kind": "critter",
  "recipe": {
    "kind": "critter",
    "name": "Pingo",
    "species": "dog",
    "breed": "dalmata",
    "size": "small",
    "palette": {
      "leather": "#1d1b26"
    }
  }
}

• 200 OK
• 400 No recipe (recipe_required), invalid code (invalid_code) or unknown kind (invalid_kind).
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Model image preview

Server-rendered PNG portrait, 128 or 256 px, of a model (animal, Cartoon animal, human, Cartoon, tree...), rendered like the PNG download, without a license. Does not use a download; same hourly limit as the character preview.

Low poly husky (creature, free)

{
  "kind": "creature",
  "recipe": {
    "kind": "creature",
    "name": "Nevasca",
    "species": "dog",
    "breed": "husky",
    "eyes": "happy",
    "neck": "scarf",
    "size": "medium",
    "finish": "lowpoly",
    "palette": {
      "skin": "#d63a3a"
    }
  },
  "size": 256
}

Cartoon doberman (critter)

{
  "kind": "critter",
  "recipe": {
    "kind": "critter",
    "name": "Thor",
    "species": "dog",
    "breed": "doberman",
    "traits": {
      "ears": "floppy"
    },
    "size": "medium"
  },
  "size": 256
}

• 200 PNG image
• 400 Invalid recipe, kind or size.
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).
• 503 Render queue full.

Create a file (GLB, OBJ, sprites, PNG)

Validates, takes 1 download from the quota (batch: N) and queues the file. Answers 202 with the id; follow it with GET /exports/{id}. Character: `config` or `code`. Model: `kind` + `recipe` (or `kind` + `code`), with the model's animations in `clips` (POST /models/validate lists them) and, optionally, animator clips in `myClips`. `compress: true` (GLB only) returns a Draco-compressed GLB, much smaller; the same model compressed or not counts as one download. Send an Idempotency-Key header to retry safely.

Character GLB

{
  "config": {
    "name": "Bomber",
    "parts": {
      "head": "head_round",
      "hair": "hair_short",
      "eyes": "eyes_big",
      "mouth": "mouth_open",
      "beard": "beard_none",
      "helmet": "helm_bomber",
      "body": "body_bomber",
      "legs": "legs_cargo",
      "boots": "boots_sneakers",
      "gloves": "gloves_cartoon",
      "back": "back_bombs",
      "handR": "r_bomb",
      "handL": "l_none"
    },
    "palette": {
      "skin": "#f2c39b",
      "hair": "#5a3a22",
      "eyes": "#2fb3c4",
      "primary": "#f07f2a",
      "secondary": "#2f4f8f",
      "detail": "#f2c534",
      "metal": "#b9c2cf",
      "leather": "#5a3a22",
      "glow": "#ff6b3d",
      "dark": "#1d1b26",
      "white": "#f7f7fb",
      "tongue": "#e2697c",
      "flash": "#ffd24a",
      "fire": "#ff6a1a",
      "ice": "#8fe8ff",
      "venom": "#7ee83c",
      "bolt": "#ffe24d",
      "void": "#a052ff",
      "holy": "#fff0a8"
    }
  },
  "format": "glb",
  "fps": 24,
  "clips": [
    "Walk",
    "Run",
    "Attack"
  ]
}

Cartoon doberman, compressed GLB (critter)

{
  "kind": "critter",
  "recipe": {
    "kind": "critter",
    "name": "Thor",
    "species": "dog",
    "breed": "doberman",
    "traits": {
      "ears": "floppy"
    },
    "size": "medium"
  },
  "format": "glb",
  "fps": 30,
  "clips": [
    "Idle",
    "Walk",
    "Run"
  ],
  "compress": true
}

Low poly husky sprites (creature)

{
  "kind": "creature",
  "recipe": {
    "kind": "creature",
    "name": "Nevasca",
    "species": "dog",
    "breed": "husky",
    "eyes": "happy",
    "neck": "scarf",
    "size": "medium",
    "finish": "lowpoly",
    "palette": {
      "skin": "#d63a3a"
    }
  },
  "format": "sprites",
  "fps": 12,
  "clips": [
    "Walk",
    "Run"
  ],
  "dirs": 4,
  "size": 128
}

• 202 Queued
• 400 Invalid request (format, fps, clips, sprites, batch, item, compress, kind, recipe).
• 401 Missing or invalid API key.
• 402 Free monthly quota reached (quota) or a Pro-only option: sprites over 128 px / 4 directions, batch (pro_only).
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 409 Idempotency-Key still in progress.
• 422 Idempotency-Key reused with another body.
• 429 Rate limited (see Retry-After and RateLimit-* headers).
• 503 Export queue full (quota returned).

Export status

Status, progress, license and, when ready, a signed download link (15 min). With `wait` (up to 25 s) the response waits for completion.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 404 Unknown, expired or not yours.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Download the file

The finished file (kept for 15 min). With the key in the header, or without a key using the signed link `token`.

• 200 File (model/gltf-binary, application/zip or image/png)
• 403 Invalid or expired signed link.
• 404 Unknown, expired or not yours.

Download history

The account's downloads (studio, API and MCP) with license number and kind, newest first. Paginate with `before`.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

AI credit balance

Balance (purchased + this month's Pro credits), cost of each generation kind and whether AI is available.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Design a character with AI

The AI (Claude) picks catalog parts and colors from a description, a reference photo (data URL JPEG/PNG/WebP, up to ~1.2 MB) or adjusts a recipe (mode: refine, with `version` or the current recipe). `target` (or `kind`) picks what to make: avatar (chibi/voxel, default; catalog parts plus custom pieces), creature (Soft/Low poly/Voxel animals; for a dog or a cat the AI picks breed and traits so the asked characteristics show, like "doberman with pointy ears"), human (realistic human), toon (Cartoon) or critter (Cartoon plush Animals: species, breed and traits for dogs and cats, size and the colors of that species' zones); for the last four the AI uses only that kind's catalog and the result comes in `recipe` ({kind, ...}, the same recipe POST /exports and /models/preview take), with warnings about what was replaced (closest_species when the animal is not in the list and became the closest one, unused_zone, wrong_species, unknown_option). Costs 3 credits for text, 4 with a photo, 2 to adjust and 1 when the same request was already made; charged up front and refunded on failure. Works on any plan: it only needs credits. Waits up to 20 s; if not done, answers 202 with the id for GET /ai/generations/{id}. Real people and brands become generic traits.

Character (avatar)

{
  "prompt": "a tall rapper with braids, dark sunglasses and a blue jacket",
  "lang": "en"
}

Cartoon doberman (critter)

{
  "target": "critter",
  "prompt": "a doberman with pointy ears",
  "lang": "en"
}

Low poly dalmatian (creature)

{
  "target": "creature",
  "prompt": "a low poly dalmatian puppy with spots and a red collar",
  "lang": "en"
}

Adjust a previous result

{
  "mode": "refine",
  "version": 19,
  "prompt": "make the ears floppy",
  "lang": "en"
}

• 200 Done (status: done) or failed (status: error, credits refunded)
• 202 Still running: poll GET /ai/generations/{id}
• 400 Invalid prompt, image, target (ai_kind) or recipe.
• 401 Missing or invalid API key.
• 402 Not enough AI credits (credits).
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).
• 503 AI unavailable or paused for today.

AI generation history

Everything the account asked the AI and what came out (recipe code to reopen for free). Reference photos are never stored.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

AI generation result

Status of a generation (owner only); with `wait` (up to 25 s) it waits for completion. Kept for 15 minutes.

• 200 OK
• 401 Missing or invalid API key.
• 403 The key lacks the scope, or the account e-mail is not confirmed.
• 404 Unknown, expired or not yours.
• 429 Rate limited (see Retry-After and RateLimit-* headers).

Check a license

Public (no key): tells whether the license exists, its kind (personal or commercial), date and format. Never reveals the owner.

• 200 OK