API y MCP de Studio Tank

Cuenta, plan y cuota

Devuelve el plan, las descargas usadas en el mes, los aleatorios restantes del día, los límites y la clave en uso.

• 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).

Catálogo de piezas, opciones y animaciones

Todo lo que puede ir en una receta: ids de pieza por categoría, estilos, zonas de color, paletas, animaciones, presets y opciones de exportación del personaje. Con `kind` (creature, critter, human, toon, tree, building, prop, vfx, world), el catálogo de ese tipo de modelo: especies, razas con rasgos y colores por defecto, rasgos que acepta cada especie, guardarropa, zonas de color y lo que pinta cada una, rangos de los controles, animaciones y opciones de exportación. Solo metadatos; nombres en el idioma pedido.

• 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).

Validar receta

Normaliza la receta (ids y colores verificados), devuelve el código corto y explica qué se reemplazó, qué quedó por defecto y qué queda oculto (p. ej. el casco oculta el pelo). Gratis.

{
  "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).

Personajes aleatorios

Genera de 1 a 10 recetas coherentes con el estilo (o de cualquier estilo). Con `seed` el resultado se repite. En el plan gratis cuenta en el límite diario de aleatorios.

{
  "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).

Vista previa en imagen

Retrato PNG de 128 o 256 px renderizado en el servidor. No gasta descarga; tiene límite por hora (gratis 30, Pro 300, sumado con /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.

Validar receta de modelo

Normaliza la receta de un tipo de modelo ({kind, recipe} o {kind, code}) con las reglas del tipo, las mismas del estudio y de la exportación, y explica qué cambió: campo que el tipo no tiene (unknown_field), id fuera de la lista (unknown_option), raza o rasgo de otra especie (wrong_species), pieza del otro género (wrong_gender), número ajustado al rango (adjusted), color inválido (invalid_color), zona que el modelo no pinta (unused_zone) o deja fija (fixed_zone), elementos descartados (dropped). Devuelve la receta normalizada, su código (JSON en base64url) y las animaciones del modelo. Gratis.

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).

Vista previa de modelo en imagen

Retrato PNG de 128 o 256 px de un modelo (animal, animal cartoon, humano, cartoon, árbol...), renderizado en el servidor como el PNG de la descarga, sin licencia. No gasta descarga; usa el mismo límite por hora que la vista previa del personaje.

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.

Crear archivo (GLB, OBJ, sprites, PNG)

Valida, descuenta 1 descarga de la cuota (lote: N) y pone el archivo en la cola. Responde 202 con el id; síguelo con GET /exports/{id}. Personaje: `config` o `code`. Modelo: `kind` + `recipe` (o `kind` + `code`), con las animaciones del modelo en `clips` (POST /models/validate las lista) y, si quieres, las del animador en `myClips`. `compress: true` (solo GLB) entrega el GLB con Draco, mucho más liviano; el mismo modelo con o sin compresión cuenta como una sola descarga. Usa la cabecera Idempotency-Key para reintentar con seguridad.

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).

Estado del archivo

Estado, progreso, licencia y, cuando está listo, un enlace firmado de descarga (15 min). Con `wait` (hasta 25 s) la respuesta espera a que termine.

• 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).

Descargar el archivo

El archivo listo (queda 15 min en el servidor). Con la clave en la cabecera, o sin clave usando el `token` del enlace firmado.

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

Historial de descargas

Descargas de la cuenta (estudio, API y MCP) con número y tipo de licencia, de la más nueva a la más antigua. Pagina con `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).

Saldo de créditos de IA

Saldo (comprados + del Pro en el mes), costo de cada tipo de generación y si la IA está disponible.

• 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).

Crear personaje con IA

La IA (Claude) elige piezas y colores del catálogo a partir de una descripción, una foto de referencia (data URL JPEG/PNG/WebP, hasta ~1,2 MB) o ajusta una receta (mode: refine, con `version` o la receta actual). `target` (o `kind`) elige qué crear: avatar (chibi/voxel, por defecto; piezas del catálogo y piezas a medida), creature (animales Suave/Low poly/Vóxel; en perros y gatos la IA elige raza y rasgos para que aparezcan las características pedidas, como "dóberman de orejas erguidas"), human (humano realista), toon (Cartoon) o critter (Animales Cartoon de peluche: especie, raza y rasgos en perros y gatos, tamaño y colores de las zonas de la especie); en los cuatro últimos la IA usa solo el catálogo del tipo y el resultado llega en `recipe` ({kind, ...}, la misma receta de POST /exports y /models/preview), con avisos de lo que se reemplazó (closest_species cuando el animal no existe y se volvió el más parecido, unused_zone, wrong_species, unknown_option). Cuesta 3 créditos por texto, 4 con foto, 2 por ajuste y 1 cuando el mismo pedido ya se hizo; se cobra antes y se devuelve si falla. Vale en cualquier plan: solo necesita créditos. Espera hasta 20 s; si no terminó, responde 202 con el id para GET /ai/generations/{id}. Personas reales y marcas se vuelven rasgos genéricos.

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.

Historial de creación con IA

Todo lo que la cuenta pidió a la IA y lo que salió (código de la receta para reabrir sin costo). La foto de referencia nunca se guarda.

• 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).

Resultado de la creación con IA

Estado de una generación (solo del dueño); con `wait` (hasta 25 s) espera a que termine. Disponible por 15 minutos.

• 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).

Verificar una licencia

Público (sin clave): indica si la licencia existe, su tipo (personal o comercial), la fecha y el formato. No revela al dueño.

• 200 OK