API e MCP do Studio Tank

Conta, plano e cota

Mostra o plano, os downloads usados no mês, os aleatórios restantes do dia, os limites e a chave usada.

• 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 peças, opções e animações

Tudo o que pode entrar numa receita: ids de peça por categoria, estilos, zonas de cor, paletas, animações, presets e opções de exportação do personagem. Com `kind` (creature, critter, human, toon, tree, building, prop, vfx, world), o catálogo daquele tipo de modelo: espécies, raças com traços e cores padrão, traços que cada espécie aceita, guarda-roupa, zonas de cor e o que cada uma pinta, faixas dos controles, animações e opções de exportação. Só metadados; nomes no 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 receita

Normaliza a receita (ids e cores conferidos), devolve o código curto e explica o que foi trocado, o que ficou no padrão e o que fica escondido (ex.: elmo esconde cabelo). Não gasta cota.

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

Sortear personagens

Gera de 1 a 10 receitas coerentes com o estilo (ou de qualquer estilo). Com `seed` o resultado se repete. No grátis conta no limite diário de aleatórios.

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

Prévia em imagem

Retrato PNG de 128 ou 256 px renderizado no servidor. Não gasta download; tem limite por hora (grátis 30, Pro 300, somado com /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 receita de modelo

Normaliza a receita de um tipo de modelo ({kind, recipe} ou {kind, code}) com as regras do tipo, as mesmas do estúdio e da exportação, e explica o que mudou: campo que o tipo não tem (unknown_field), id fora da lista (unknown_option), raça ou traço de outra espécie (wrong_species), peça do outro gênero (wrong_gender), número preso na faixa (adjusted), cor inválida (invalid_color), zona que o modelo não pinta (unused_zone) ou fixa (fixed_zone), itens descartados (dropped). Devolve a receita normalizada, o código (base64url do JSON) e as animações que o modelo tem. Não gasta cota.

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

Prévia de modelo em imagem

Retrato PNG de 128 ou 256 px de um modelo (animal, animal cartoon, humano, cartoon, árvore...), renderizado no servidor como o PNG do download, sem licença. Não gasta download; usa o mesmo limite por hora da prévia do personagem.

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.

Criar arquivo (GLB, OBJ, sprites, PNG)

Valida, desconta 1 download da cota (lote: N) e coloca o arquivo na fila. Responde 202 com o id; acompanhe em GET /exports/{id}. Personagem: `config` ou `code`. Modelo: `kind` + `recipe` (ou `kind` + `code`), com as animações do modelo em `clips` (POST /models/validate lista quais) e, se quiser, as do animador em `myClips`. `compress: true` (só GLB) entrega o GLB com Draco, bem menor; o mesmo modelo com ou sem compressão conta como um download só. Use o cabeçalho Idempotency-Key para repetir com segurança.

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

Status do arquivo

Status, progresso, licença e, quando pronto, um link assinado de download (15 min). Com `wait` (até 25 s) a resposta espera terminar.

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

Baixar o arquivo

O arquivo pronto (fica 15 min no servidor). Com a chave no cabeçalho, ou sem chave usando o `token` do link assinado.

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

Histórico de downloads

Downloads da conta (estúdio, API e MCP) com número e tipo da licença, do mais novo ao mais antigo. Pagine com `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 + do Pro no mês), custo de cada tipo de geração e se a IA está disponível.

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

Criar personagem com IA

A IA (Claude) escolhe peças e cores do catálogo a partir de uma descrição, de uma foto de referência (data URL JPEG/PNG/WebP, até ~1,2 MB) ou ajusta uma receita (mode: refine, com `version` ou a receita atual). `target` (ou `kind`) escolhe o que criar: avatar (chibi/voxel, padrão; peças do catálogo e peças sob medida), creature (animais Fofo/Low poly/Voxel; em cachorro e gato a IA escolhe raça e traços para as características pedidas aparecerem, como "doberman de orelhas em pé"), human (humano realista), toon (Cartoon) ou critter (Animais Cartoon de pelúcia: espécie, raça e traços no cachorro e no gato, tamanho e cores das zonas da espécie); nos quatro últimos a IA usa só o catálogo do tipo e o resultado vem em `recipe` ({kind, ...}, a mesma receita de POST /exports e /models/preview), com avisos do que foi trocado (closest_species quando o bicho não existe e virou o mais parecido, unused_zone, wrong_species, unknown_option). Custa 3 créditos por texto, 4 com foto, 2 por ajuste e 1 quando o mesmo pedido já foi feito; cobrado antes e devolvido se falhar. Vale em qualquer plano: só precisa de créditos. Espera até 20 s; se não terminou, responde 202 com o id para GET /ai/generations/{id}. Pessoas reais e marcas viram traços 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.

Histórico da criação por IA

Tudo o que a conta pediu à IA e o que saiu (código da receita para reabrir sem custo). A foto de referência nunca é guardada.

• 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 da criação por IA

Status de uma geração (só do dono); com `wait` (até 25 s) espera terminar. Fica disponível 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).

Conferir uma licença

Público (sem chave): diz se a licença existe, o tipo (pessoal ou comercial), a data e o formato. Não revela o dono.

• 200 OK