API e MCP do Studio Tank

Começar em 3 passos

1. Entre no estúdio, abra o menu da conta e crie uma chave de API. Ela aparece uma única vez: guarde num cofre ou variável de ambiente. Criar chave no estúdio →
2. Sorteie um personagem (ou monte a receita com ids do catálogo):

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

   ⧉
3. Peça o arquivo e espere ficar pronto; a resposta traz um link de download que vale 15 minutos:

   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)

   ⧉

Especificação OpenAPI 3.1 para Postman, Insomnia ou geradores de SDK: https://avatar.tankpvp.com/api/v1/openapi.json

Autenticação

Envie a chave no cabeçalho Authorization: Bearer avs_… em toda chamada. A API não aceita o cookie do site e não libera CORS: use a chave só no servidor, nunca em JavaScript de página. Cada conta pode ter até 5 chaves ativas, com escopos, e revogar uma corta o acesso na hora.

Limites e cota

A cota é da conta: o que você baixa pelo estúdio, pela API e pelo MCP soma no mesmo contador. Os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostram o limite por minuto; ao estourar, a resposta é 429 com Retry-After.

Arquivos, idempotência e licença

• Fila: POST /exports responde 202 com o id. Consulte GET /exports/{id}?wait=20: a resposta espera até 25 s e evita várias consultas.
• Idempotência: mande Idempotency-Key no POST /exports. Repetir com a mesma chave e o mesmo corpo em 24 h devolve o mesmo arquivo, sem gastar cota de novo.
• Download: o arquivo fica 15 minutos no servidor. Baixe com a sua chave ou pelo download.url assinado (não precisa de chave; ideal para entregar a quem pediu).
• Licença: todo arquivo leva um número AS-XXXXX-XXXXX (no GLB, no PNG e no LICENCA.txt dos .zip). Qualquer pessoa confere em GET /licenses/{id}, sem ver o dono.
• Receitas: mande config (peças e cores) ou code (o código curto do link do estúdio). Ids errados viram o padrão; /avatars/validate explica o que mudou.

Erros

Todo erro vem no mesmo formato: { "error": { "code", "message", "docs" } }. Use o code no seu código (ele não muda); a mensagem é para pessoas.

MCP: conecte o Claude e outros assistentes

O servidor MCP em /mcp deixa um assistente de IA montar personagens com você: ele consulta o catálogo, mostra a prévia em imagem e, quando você aprovar, exporta e entrega o link. Usa a mesma chave, a mesma cota e a mesma licença da 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 e outros clientes com MCP por HTTP (arquivo de configuração):

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

Claude Desktop (via mcp-remote, precisa do Node instalado):

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

Ferramentas disponíveis

Console MCP (testar aqui)

Referência

Conta, plano e cota

Peças, estilos, animações e cores

Validar, sortear e pré-visualizar

{
  "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
}

Arquivos (usam a cota de downloads)

{
  "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"
  ]
}

Criação por IA (usa créditos de IA)

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

Conferência pública de licença