API y MCP de Studio Tank

Empieza en 3 pasos

1. Entra al estudio, abre el menú de la cuenta y crea una clave de API. Se muestra una sola vez: guárdala en un gestor de secretos o una variable de entorno. Crear clave en el estudio →
2. Sortea un personaje (o arma la receta con ids del 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. Pide el archivo y espera a que esté listo; la respuesta trae un enlace de descarga válido por 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)

   ⧉

Especificación OpenAPI 3.1 para Postman, Insomnia o generadores de SDK: https://avatar.tankpvp.com/api/v1/openapi.json

Autenticación

Envía la clave en la cabecera Authorization: Bearer avs_… en cada llamada. La API no acepta la cookie del sitio y no tiene CORS: usa la clave solo en tu servidor, nunca en JavaScript de página. Cada cuenta puede tener hasta 5 claves activas con alcances, y revocar una corta el acceso al instante.

Límites y cuota

La cuota es de la cuenta: lo que descargas por el estudio, la API y el MCP suma en el mismo contador. Las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset muestran el límite por minuto; al superarlo recibes 429 con Retry-After.

Archivos, idempotencia y licencia

• Cola: POST /exports responde 202 con el id. Consulta GET /exports/{id}?wait=20: la respuesta espera hasta 25 s y evita muchas consultas.
• Idempotencia: envía Idempotency-Key en POST /exports. Repetir con la misma clave y el mismo cuerpo en 24 h devuelve el mismo archivo sin gastar cuota otra vez.
• Descarga: el archivo queda 15 minutos en el servidor. Descárgalo con tu clave o por el download.url firmado (no necesita clave; ideal para entregarlo a quien lo pidió).
• Licencia: cada archivo lleva un número AS-XXXXX-XXXXX (en el GLB, el PNG y el LICENCA.txt de los .zip). Cualquiera lo verifica en GET /licenses/{id} sin ver al dueño.
• Recetas: envía config (piezas y colores) o code (el código corto del enlace del estudio). Los ids incorrectos vuelven al valor por defecto; /avatars/validate explica qué cambió.

Errores

Todo error tiene el mismo formato: { "error": { "code", "message", "docs" } }. Usa el code en tu código (no cambia); el mensaje es para personas.

MCP: conecta Claude y otros asistentes

El servidor MCP en /mcp permite que un asistente de IA cree personajes contigo: consulta el catálogo, muestra la vista previa en imagen y, cuando apruebes, exporta y te entrega el enlace. Usa la misma clave, cuota y licencia que la 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 y otros clientes con MCP por HTTP (archivo de configuración):

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

Claude Desktop (vía mcp-remote, necesita Node instalado):

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

Herramientas disponibles

Consola MCP (pruébalo aquí)

Referencia

Cuenta, plan y cuota

Piezas, estilos, animaciones y colores

Validar, sortear y previsualizar

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

Archivos (usan la cuota de descargas)

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

Creación con IA (usa créditos de IA)

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

Verificación pública de licencia