sapiens-mcp 1.62.8 → 1.63.1

package/dist/skills.js

@@ -206,6 +206,8 @@ Dar som a um vídeo SEU já pronto é \`sapiens_video action=sonorize\`, não é
 
 \`action=models\` (sem custo, sem login) lista os modelos ativos com durações, resoluções, disponibilidade e a FAIXA de preço: o padrão, o piso e o teto, cada um dizendo em qual configuração acontece. Motor de preço-por-segundo não tem "um preço": o mesmo modelo custa 3x mais em 1080p e 30s do que em 720p e 5s.
 
+Dois campos do payload evitam garimpo na lista. bestFor diz pra que o motor serve (audio = som nativo, fala = lip-sync, referencia = aceita referência de quem aparece, movimento = precisa de vídeo-guia, longo = passa dos 15s): filtre por aqui antes de comparar preço. family + variant dizem quem é o mesmo motor em geração ou tier diferente: as seis linhas de Seedance (1.0 Fast, 1.5 Pro, 2.0, 2.0 Fast, 2.0 Mini, 2.5) são UM motor, não seis. Escolha a família pelo trabalho, depois a variante pela conta.
+
 \`action=price\` (sem custo, sem login) cota a configuração EXATA antes de rodar: passe \`model\`, \`durationSec\`, \`resolution\` e \`audio\` e receba o número que vai ser debitado, calculado pela mesma função que cobra. Ela também avisa quando o motor não aceita o que você pediu e vai cobrar outra coisa (\`clamped\`), o que acontece quando a duração não existe no enum ou a resolução cai num tier diferente.
 
 Use \`price\` sempre que a pessoa perguntar quanto custa, e ANTES de qualquer \`create\` que não seja o default. Dizer o piso como se fosse o preço final é o jeito mais rápido de queimar a confiança dela: a cobrança vem maior e a culpa é sua.
@@ -230,6 +232,8 @@ Duração é o que pesa aqui, não o modelo: um take de 30s em 720p passa de 40
 
 ## Os outros modelos
 
+- \`sapiens-video-h3\`: MiniMax H3, o mais barato por pixel da casa, com som nativo, texto ou imagem. A duração depende da resolução: \`2k\` vai até 10s, \`768p\` vai até 15s (o motor de 2K é lento demais pra 15s e o take se perderia no meio). Aceita até 9 imagens e 3 vídeos de referência, e é o caminho de take LONGO com personagem travada. Referência e frame inicial não vão juntos: escolha um. Sem \`resolution\` cai no 2k, que custa 40% mais por segundo.
+- \`sapiens-video-h3-spicy\` e \`sapiens-video-seedance-spicy\`: os mesmos motores SEM freio de conteúdo. Os dois partem de uma IMAGEM sua (não fazem texto puro), e é isso que trava a identidade: quem aparece já veio pronto na imagem, o motor só dá movimento. O H3 Spicy é o mais barato e o mais rápido da casa (250 Sinapses o segundo em 480p, 3 a 15s); o Seedance Spicy tem o peso do 2.0 e para em 10s nos tiers acima de 480p.
 - \`sapiens-video-kling\`: Kling 3.0 Pro, anima imagem, 3 a 15s, som opcional.
 - \`sapiens-video-wan\`: WAN 2.5, imagem que fala ou canta, com lip-sync, 5 ou 10s.
 - \`sapiens-video-wan-3\`: WAN 3.0, texto ou imagem, som nativo, frame final e 1080p, 5 a 10s.
@@ -256,7 +260,7 @@ O \`brief\` aceita \`subject\`, \`persona\`, \`hook\` (\`line\` e \`emotion\`),
 
 ## Fluxo storyboard (o que dá o melhor resultado)
 
-Até 4 imagens de REFERÊNCIA via \`referenceImageIds\` / \`referenceImageUrls\` / \`referenceImagePaths\` guiam estilo, personagem e composição SEM virar o primeiro frame.
+Imagens de REFERÊNCIA via \`referenceImageIds\` / \`referenceImageUrls\` / \`referenceImagePaths\` guiam estilo, personagem e composição SEM virar o primeiro frame. O teto é do motor: 4 no Seedance 2.0, 9 no H3.
 
 1. Gere a folha de key poses com \`sapiens_image templateSlug='storyboard-sapiens-v1'\`.
 2. Passe folha e personagem como refs num text-to-video.
@@ -304,6 +308,15 @@ Proibidos no prompt: "tarot card illustration", "intimate scale", "card-style po
 
 \`action=generate\` com \`prompt\`, \`model\` e \`aspectRatio\`. \`action=models\` (sem custo, sem login) lista o catálogo vivo com preço atual, resolução máxima e se o modelo aceita referência.
 
+## Escolher motor em dois passos
+
+A lista de action=models é longa e ordenada por PREÇO, que não é a pergunta de quem vai gerar. Três campos do payload resolvem isso:
+
+- bestFor: pra que o motor serve, num vocabulário fechado (foto, anime, texto pra palavra legível na arte, personagem pra segurar a mesma pessoa, adulto). FILTRE por aqui antes de comparar preço.
+- family + variant: motores com a MESMA family são o mesmo motor em versão diferente (Krea 2 tem Realism, Livre e Base; Gemini tem 3 Pro e 3.1 Flash). O retorno traz um índice families já montado.
+
+O caminho: filtre por bestFor, escolha a família, e só então compare as variantes dela entre si. Trocar de família porque uma variante é mais barata costuma trocar o resultado inteiro; trocar de variante dentro da família troca preço e acabamento, não o motor.
+
 ## Multi-referência
 
 Combine até 4 imagens como referência numa geração só:

package/dist/tools/image.js

@@ -136,6 +136,17 @@ export async function image(args) {
             .map((m) => ({
             id: m.id,
             label: m.label,
+            // Família + variante: várias entradas da lista são o MESMO motor em
+            // tempero ou geração diferente (Krea 2 Realism/Livre/Base, Gemini 3
+            // Pro/3.1 Flash). Sem estes dois campos o cliente vê ids soltos e trata
+            // como motores sem relação, que foi o mesmo problema que a prateleira
+            // do browser tinha antes de agrupar. Ausência = motor sozinho.
+            family: m.family ?? null,
+            variant: m.variantLabel ?? null,
+            // Pra que este motor serve, no vocabulário fechado do catálogo: foto,
+            // anime, texto, personagem, adulto. É o que responde "qual motor pra
+            // isso" sem o cliente ter que interpretar vinte taglines.
+            bestFor: m.bestFor ?? [],
             priceSinapses: m.effectivePriceSinapses,
             maxResolution: m.maxResolution ?? "4K",
             resolutionAdders: m.resolutionAdders,
@@ -143,12 +154,26 @@ export async function image(args) {
             degen: /^(civitai-|wavespeed-|fal-)/.test(String(m.id)),
             note: m.description ?? null,
         }));
+        // Índice por família, pro cliente escolher em dois passos como a tela faz:
+        // primeiro o motor, depois a versão. Só entra família com 2+ variantes.
+        const families = {};
+        for (const m of models) {
+            if (!m.family)
+                continue;
+            (families[m.family] ??= { variants: [] }).variants.push(m.id);
+        }
+        for (const key of Object.keys(families)) {
+            if (families[key].variants.length < 2)
+                delete families[key];
+        }
         return {
             count: models.length,
             default: "nano-banana-2",
             models,
+            families,
             note: "priceSinapses é o preço COBRADO em 1K (já com override admin). Acima de 1K some o adder de resolutionAdders[size], que vem clampado ao teto do motor: em modelo que para em 2K, a chave '4K' repete o valor de 2K porque é isso que a cobrança aplica quando você pede 4K nele. " +
-                "Preço final = priceSinapses + resolutionAdders[size]. degen=+18 (gate na galeria).",
+                "Preço final = priceSinapses + resolutionAdders[size]. degen=+18 (gate na galeria). " +
+                "Modelos com a MESMA family são o mesmo motor em versão diferente (o variant diz qual): compare preço e nota entre eles antes de trocar de família.",
         };
     }
     const sessionToken = getSessionToken();

package/dist/tools/reference.js

@@ -39,12 +39,13 @@ export const referenceSchema = z.object({
         // set/2026). Fica no enum, depreciado e sem aparecer nas descrições, porque
         // client publicado continua mandando ele e a regra de retrocompat da casa
         // proíbe quebrar quem está atrasado. O servidor aceita os dois.
-        .enum(["history", "favorites", "videos", "stock_video", "acervo", "characters", "depth_map", "deepshadow"])
+        .enum(["history", "favorites", "videos", "stock_video", "acervo", "characters", "depth_map", "pose_map", "deepshadow"])
         .optional()
         .describe("Só 'browse': qual banco navegar: 'history' (suas imagens recentes), 'favorites' (as que você curtiu), " +
         "'videos' (seus vídeos), 'stock_video' (Banco de Vídeo da casa: clipes/B-roll prontos, aceita term/orientation/loopOnly), " +
         "'acervo' (stock + comunidade públicos de IMAGEM), 'characters' (personagens), " +
-        "'depth_map' (guias de movimento: os SEUS com shadowSource='mine', ou o banco curado da casa por default)."),
+        "'depth_map' (guias de movimento: os SEUS com shadowSource='mine', ou o banco curado da casa por default), " +
+        "'pose_map' (seu banco privado de POSE: mapa de profundidade de corpo num quadro parado, aceita term/orientation)."),
     handle: z
         .string()
         .optional()
@@ -82,7 +83,7 @@ export const referenceSchema = z.object({
     orientation: z
         .enum(["vertical", "horizontal", "square"])
         .optional()
-        .describe("Só bucket 'stock_video': filtra formato (vertical 9:16, horizontal 16:9, square 1:1)."),
+        .describe("Buckets 'stock_video' e 'pose_map': filtra formato (vertical 9:16, horizontal 16:9, square 1:1)."),
     loopOnly: z
         .boolean()
         .optional()
@@ -116,7 +117,7 @@ export async function reference(args) {
     if (args.action === "browse") {
         if (!args.bucket) {
             return {
-                error: "browse exige `bucket` (history | favorites | videos | stock_video | acervo | characters | depth_map).",
+                error: "browse exige `bucket` (history | favorites | videos | stock_video | acervo | characters | depth_map | pose_map).",
             };
         }
         const res = await convexAction("mcpReferences:referenceBrowse", {
@@ -144,6 +145,10 @@ export async function reference(args) {
             note =
                 "Guias de movimento (mapa de profundidade). Use a `url` em sapiens_video referenceVideoUrls: a coreografia e a câmera do clipe guiam o take. `thumbnailUrl` é só preview (a soma com esqueleto), nunca mande ela como driving. Teto de duração varia por motor.";
         }
+        else if (args.bucket === "pose_map") {
+            note =
+                "Poses do SEU banco privado (mapa de profundidade de corpo). Use a `url` em sapiens_image referenceImageUrls pra guiar a POSE da figura, do mesmo jeito que o depth_map guia o movimento no vídeo. `thumbnailUrl` é só preview da grade. É material privado seu: a peça gerada a partir dele é geração normal e publica normal, mas a pose em si não é acervo público da casa.";
+        }
         else if (args.bucket === "acervo" || args.bucket === "characters") {
             note =
                 "São referências públicas: use a `url` (characters trazem mainImageUrl + imageUrls) em sapiens_image referenceImageUrls, ou em sapiens_video startImageUrl/endImageUrl. Não são suas, então NÃO entram em sourceImageIds.";

package/dist/tools/video.js

@@ -77,12 +77,25 @@ import { httpUrl } from "../schema.js";
  *                                   Motor puro: SEM áudio, SEM referência, SEM frame final.
  *   - sapiens-video-hailuo-pro     Hailuo 2.3 Pro — o mesmo em 1080p, 5s fixo (duração não é param).
  *                                   É o 1080p mais barato da casa depois do Seedance 1.0 Fast.
- *   - sapiens-video-h3             MiniMax H3 — 2K (2560x1440) com ÁUDIO nativo, 5/6/8/10s (t2v/i2v),
- *                                   frame final (role 'end'). O menor custo por pixel da prateleira.
- *                                   Áudio vem sempre e já está no preço (não tem toggle). NÃO aceita
- *                                   imagem de referência: no H3 isso é outro endpoint, ainda fora.
- *                                   O provider faz até 15s; a casa para em 10 (o render de 5s leva
- *                                   ~3min e o poll do backend morre em 8).
+ *   - sapiens-video-h3             MiniMax H3 — ÁUDIO nativo, frame final (role 'end'), t2v/i2v. O
+ *                                   menor custo por pixel da prateleira. Áudio vem sempre e já está
+ *                                   no preço (não tem toggle). A DURAÇÃO DEPENDE DA RESOLUÇÃO: em
+ *                                   '2k' (2560x1440) vai até 10s, em '768p' vai até 15s. Não é
+ *                                   escolha de catálogo, é o poll do backend: 2K de 15s leva mais
+ *                                   que os 8min e o kill não devolve Sinapse. Sem `resolution` cai
+ *                                   no 2k, que custa 40% mais por segundo.
+ *                                   ACEITA referência desde set/2026: até 9 imagens (role 'ref') e 3
+ *                                   vídeos (role 'refvideo', somando 15s), que é o caminho de take
+ *                                   longo com personagem travada. Referência e frame inicial são
+ *                                   EXCLUSIVOS (endpoints diferentes no provider): mande um dos dois.
+ *   - sapiens-video-h3-spicy       MiniMax H3 Spicy — o H3 SEM freio de conteúdo, a partir de uma
+ *                                   imagem sua (i2v puro: a identidade entra pela imagem, não pelo
+ *                                   texto). 3 a 15s, 480p/768p/1080p, som nativo, frame final. É o
+ *                                   segundo de vídeo mais barato da casa (250 Sinapses/s em 480p) e
+ *                                   o render mais rápido (5s em 480p sai em meio minuto).
+ *   - sapiens-video-seedance-spicy Seedance 2.0 Spicy — o Seedance 2.0 SEM freio, também i2v puro.
+ *                                   Som nativo. 4 a 15s em 480p; em 720p e 1080p para em 10s até
+ *                                   alguém medir o render nesses tiers.
  *   - sapiens-video-wan            WAN 2.5 — imagem que fala/canta (áudio+lip-sync nativo), 5/10s (i2v)
  *   - sapiens-video-kling-motion   Kling Motion — transfere o movimento de um vídeo pra uma imagem
  *                                   (PRECISA de pessoa com tronco visível na imagem E no vídeo;
@@ -133,6 +146,8 @@ const VIDEO_MODELS = [
     "sapiens-video-hailuo",
     "sapiens-video-hailuo-pro",
     "sapiens-video-h3",
+    "sapiens-video-h3-spicy",
+    "sapiens-video-seedance-spicy",
     "sapiens-video-wan",
     "sapiens-video-kling-motion",
     "sapiens-video-shot-mimic",
@@ -289,15 +304,15 @@ export const videoSchema = z.object({
     durationSec: z
         .number()
         .optional()
-        .describe("action=create e action=price: duração em segundos (Omni ignora). Seedance 2.0/Shot Mimic 4-15, Seedance 2.5 4-30 (o preço acompanha: confirme a duração com a pessoa antes de passar de 15), Seedance 1.5 4-12, Kling 3-15, WAN 5/10, H3 5/6/8/10. " +
+        .describe("action=create e action=price: duração em segundos (Omni ignora). Seedance 2.0/Shot Mimic 4-15, Seedance 2.5 4-30 (o preço acompanha: confirme a duração com a pessoa antes de passar de 15), Seedance 1.5 4-12, Kling 3-15, WAN 5/10, H3 5/6/8/10 em 2k e 5/6/8/10/12/15 em 768p. " +
         "O PREÇO ESCALA COM A DURAÇÃO. Omitir não é 'a config padrão da casa': duração ausente, ou fora do leque do motor, cai no PISO de duração do motor. " +
         "action=shadows: duração do vídeo-fonte, se souber (cobra 200/s; sem ela, flat ~2000)."),
     resolution: z
-        .enum(["480p", "720p", "1080p"])
+        .enum(["480p", "720p", "1080p", "768p", "2k"])
         .optional()
-        .describe("action=create e action=price: resolução (Seedance/WAN/Shot Mimic). NÃO existe default 720p aqui: resolução ausente, ou fora do que o motor aceita, cai no tier MAIS CARO do motor. " +
+        .describe("action=create e action=price: resolução (Seedance/WAN/Shot Mimic/H3). NÃO existe default 720p aqui: resolução ausente, ou fora do que o motor aceita, cai no tier MAIS CARO do motor. " +
         "É isso que faz um create sem este campo custar muito mais que o piso do catálogo (em sapiens-video-seedance vira 1080p, não 480p). Passe sempre a resolução que você quer pagar, e confira com action=price antes. " +
-        "Kling e a linha Hailuo/H3 não usam este campo (resolução fixa pelo motor)."),
+        "O H3 usa '768p' ou '2k' (sem eles cai no 2k, que custa 40% mais por segundo). Kling e a linha Hailuo 2.3 não usam este campo (resolução fixa pelo motor)."),
     audio: z
         .boolean()
         .optional()
@@ -492,6 +507,14 @@ export async function video(args) {
             id: m.id,
             engine: m.engine,
             label: m.label,
+            // Família + variante: o Seedance sozinho tem SEIS entradas nesta lista
+            // (1.0 Fast, 1.5 Pro, 2.0, 2.0 Fast, 2.0 Mini, 2.5) e são o mesmo motor
+            // em geração/tier diferente. Sem os dois campos o cliente lê seis
+            // motores sem relação. Ausência = motor sozinho.
+            family: m.family ?? null,
+            variant: m.variantLabel ?? null,
+            // Pra que este motor serve: audio, fala, referencia, movimento, longo.
+            bestFor: m.bestFor ?? [],
             // "por-segundo" = o preço MUDA com duração, resolução e (no Kling) áudio.
             // "por-clipe" = preço fixo, config não mexe na conta.
             priceMode: m.priceMode ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.62.8",
+  "version": "1.63.1",
   "mcpName": "com.sapiensinteticos/sapiens",
   "description": "MCP server pra operar o Sapiens Sintéticos (sapiensinteticos.com) pelo Claude Code: gerar imagem, escrever artigo, voz, música e mais, na sua conta. Login pelo código de sapiensinteticos.com/conectar-claude.",
   "type": "module",