Studio Tank API and MCP

Get started in 3 steps

1. Sign in to the studio, open the account menu and create an API key. It is shown only once: keep it in a vault or an environment variable. Create a key in the studio →
2. Roll a random character (or build the recipe with catalog ids):

   curl -s https://avatar.tankpvp.com/api/v1/avatars/random \
     -H "Authorization: Bearer $AVATAR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"style": "mago"}'

   ⧉
3. Request the file and wait for it; the response carries a download link valid for 15 minutes:

   curl -s https://avatar.tankpvp.com/api/v1/exports \
     -H "Authorization: Bearer $AVATAR_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: meu-pedido-001" \
     -d '{"code": "<code>", "format": "glb", "fps": 24, "clips": ["Walk","Run","Attack"]}'
   
   curl -s "https://avatar.tankpvp.com/api/v1/exports/<id>?wait=20" -H "Authorization: Bearer $AVATAR_KEY"
   # → download.url (15 min)

   ⧉

OpenAPI 3.1 specification for Postman, Insomnia or SDK generators: https://avatar.tankpvp.com/api/v1/openapi.json

Authentication

Send the key in the Authorization: Bearer avs_… header on every call. The API ignores the website cookie and has no CORS: keep the key on your server, never in page JavaScript. Each account can have up to 5 active keys with scopes, and revoking one cuts access immediately.

Limits and quota

The quota belongs to the account: downloads from the studio, the API and MCP add up in the same counter. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers show the per-minute limit; when exceeded you get 429 with Retry-After.

Files, idempotency and license

• Queue: POST /exports answers 202 with the id. Ask GET /exports/{id}?wait=20: the response waits up to 25 s, so you poll less.
• Idempotency: send Idempotency-Key on POST /exports. Repeating with the same key and body within 24 h returns the same file without using quota again.
• Download: files stay on the server for 15 minutes. Download with your key or via the signed download.url (no key needed; ideal to hand over to whoever asked).
• License: every file carries a number AS-XXXXX-XXXXX (in the GLB, the PNG and LICENCA.txt inside zips). Anyone can check it at GET /licenses/{id} without seeing the owner.
• Recipes: send config (parts and colors) or code (the short code from the studio link). Wrong ids fall back to defaults; /avatars/validate explains what changed.

Errors

Every error has the same shape: { "error": { "code", "message", "docs" } }. Branch on code (it is stable); the message is for humans.

MCP: connect Claude and other assistants

The MCP server at /mcp lets an AI assistant build characters with you: it reads the catalog, shows an image preview and, once you approve, exports and hands you the link. Same key, quota and license as the API.

POSThttps://avatar.tankpvp.com/mcp

Claude Code (terminal):

claude mcp add --transport http avatar-studio https://avatar.tankpvp.com/mcp \
  --header "Authorization: Bearer $AVATAR_KEY"

Cursor, VS Code, Windsurf and other clients with HTTP MCP (config file):

{
  "mcpServers": {
    "avatar-studio": {
      "type": "http",
      "url": "https://avatar.tankpvp.com/mcp",
      "headers": {
        "Authorization": "Bearer avs_..."
      }
    }
  }
}

Claude Desktop (through mcp-remote, needs Node installed):

{
  "mcpServers": {
    "avatar-studio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://avatar.tankpvp.com/mcp",
        "--header",
        "Authorization:Bearer avs_..."
      ]
    }
  }
}

Available tools

MCP console (try it here)

Reference

Account, plan and quota

Parts, styles, clips and colors

Validate, randomize and preview

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

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

{
  "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"
    }
  },
  "size": 256
}

Files (use the download quota)

{
  "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"
    }
  },
  "format": "glb",
  "fps": 24,
  "clips": [
    "Walk",
    "Run",
    "Attack"
  ]
}

AI character design (uses AI credits)

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

Public license check