sapiens-mcp 1.101.0 → 1.102.1

package/dist/registry.js

@@ -71,7 +71,7 @@ export const TOOLS = {
         handler: carrossel,
     },
     sapiens_image: {
-        description: "Operações de imagem via Sapiens (Gemini, GPT Image 2 e 2.5, Grok, Seedream/ByteDance). Sub-actions: 'upscale' (sourceImageId de uma imagem SUA pronta: a mesma peça em resolução maior vira peça nova no acervo, a original fica; cobra Sinapses, preço fixo igual ao da ficha no site; SÍNCRONA e pode passar de 2 min, então Timeout é o cliente desistindo: olhe sapiens_gallery action=list antes de repetir), 'sombra' (sourceImageId de uma foto SUA pronta: extrai a sombra, o mapa de profundidade colorido da foto, como peça nova no acervo, pra usar de referência de pose e volume; cobra Sinapses, preço fixo; síncrona), 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 4 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); refs valem pros modelos robustos nano-banana-2/gpt-image-2-*/grok-2-image*/seedream-*; EDIÇÃO POR ÁREA: sourceImageId + maskRegions (caixas em fração da imagem) muda SÓ a região marcada e devolve o resto igual ao pixel, no nano-banana-2 e no nano-banana-max, pelo preço da geração comum; FUNDO TRANSPARENTE: transparentBackground=true devolve PNG com alpha, o recorte feito pelo próprio motor, pelo preço da geração comum e sem o Remover Fundo pago depois, só na linha GPT Image (supportsTransparentBackground em action=models; nos outros recusa sem cobrar)), 'compose' (combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, compose=montar start frame app-demo. 'request_generation' é legado e recusa sem cobrar: vídeo nasce inteiro em sapiens_video action=create. TEMPLATE: passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug. Sub-action 'models' (sem custo, sem login): lista o catálogo vivo (modelos ativos + preço cobrado em 1K com override admin + resolutionAdders, o adder por resolução já clampado ao teto de cada motor + maxResolution + se aceita referência) pra descobrir modelo/preço em vez de chutar. O preço de uma geração é priceSinapses + resolutionAdders[size], então 2K/4K custam MAIS que o número base: nunca cite o base como se fosse o total quando o size não for 1K. NOTA: generate é SÍNCRONA e cobra ao concluir; modelo pesado (Pro, gpt-image-2-high, Grok quality, 2K/4K) cai na REGRA DO TIMEOUT (cheque sapiens_gallery action=list antes de repetir, evita cobrança dupla).",
+        description: "Operações de imagem via Sapiens (Gemini, GPT Image 2 e 2.5, Grok, Seedream/ByteDance). Sub-actions: 'upscale' (sourceImageId de uma imagem SUA pronta: a mesma peça em resolução maior vira peça nova no acervo, a original fica; cobra Sinapses, preço fixo igual ao da ficha no site; SÍNCRONA e pode passar de 2 min, então Timeout é o cliente desistindo: olhe sapiens_gallery action=list antes de repetir), 'sombra' (sourceImageId de uma foto SUA pronta: extrai a sombra, o mapa de profundidade colorido da foto, como peça nova no acervo, pra usar de referência de pose e volume; cobra Sinapses, preço fixo; síncrona), 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 5 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); quem aceita e quantas chegam ao motor saem de supportsReferences e maxReferences em action=models (a ref acima do teto do motor some sem erro); EDIÇÃO POR ÁREA: sourceImageId + maskRegions (caixas em fração da imagem) muda SÓ a região marcada e devolve o resto igual ao pixel, no nano-banana-2 e no nano-banana-max, pelo preço da geração comum; FUNDO TRANSPARENTE: transparentBackground=true devolve PNG com alpha, o recorte feito pelo próprio motor, pelo preço da geração comum e sem o Remover Fundo pago depois, só na linha GPT Image (supportsTransparentBackground em action=models; nos outros recusa sem cobrar)), 'compose' (combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, compose=montar start frame app-demo. 'request_generation' é legado e recusa sem cobrar: vídeo nasce inteiro em sapiens_video action=create. TEMPLATE: passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug. Sub-action 'models' (sem custo, sem login): lista o catálogo vivo (modelos ativos + preço cobrado em 1K com override admin + resolutionAdders, o adder por resolução já clampado ao teto de cada motor + maxResolution + se aceita referência e quantas, maxReferences) pra descobrir modelo/preço em vez de chutar. O preço de uma geração é priceSinapses + resolutionAdders[size], então 2K/4K custam MAIS que o número base: nunca cite o base como se fosse o total quando o size não for 1K. O generate devolve custoSinapses, o que o extrato debitou: é esse que se cita depois. NOTA: generate é SÍNCRONA e cobra ao concluir; modelo pesado (Pro, gpt-image-2-high, Grok quality, 2K/4K) cai na REGRA DO TIMEOUT (cheque sapiens_gallery action=list antes de repetir, evita cobrança dupla).",
         schema: imageSchema,
         handler: image,
     },
@@ -221,7 +221,7 @@ export const TOOLS = {
         handler: decupagem,
     },
     sapiens_reference: {
-        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
+        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). BUSCA POR SIGNIFICADO: em history e videos, term + semantic=true acha a peça da pessoa pelo sentido mesmo quando o prompt usou outras palavras (volta até limit, do mais parecido pro menos, com score). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
         schema: referenceSchema,
         handler: reference,
     },

package/dist/skills.js

@@ -355,9 +355,11 @@ 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.
 
+O preço de \`models\` é o do 1K. Sem \`size\`, nano-banana-2, nano-banana-max e a família Krea 2 geram em 2K e somam o adder de 2K: passe \`size: "1K"\` quando o barato importar mais. O que foi debitado de verdade volta em \`custoSinapses\` no retorno do generate; cite esse, não o da lista.
+
 ## 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:
+A lista de action=models é longa e segue a ordem da prateleira da casa, não o preço, e nenhuma das duas é 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 (Flux.2 Klein tem Base, Anime, Celular e Transparência; Krea 2 tem Realism e Transparência; Gemini tem 3 Pro e Nano Banana 2.1; GPT Image tem 2 Low, 2 High, 2.5 Flare e 2.5 Sunburst). O retorno traz um índice families já montado.
@@ -369,12 +371,12 @@ O caminho: filtre por bestFor, escolha a família, e só então compare as varia
 
 ## Multi-referência
 
-Combine até 4 imagens como referência numa geração só:
+Combine até 5 imagens como referência numa geração só:
 
 - \`referenceImageUrls\`: sua galeria, o Acervo, personagens públicos (descubra em \`sapiens_character\`).
 - \`sourceImageIds\`: ids da sua galeria.
 
-Refs valem pros modelos robustos (nano-banana-2, gpt-image-2-low/high, gpt-image-2-5-flare/sunburst, grok-2-image*). Use \`sapiens_reference\` pra achar a URL certa em vez de adivinhar.
+Quem aceita e quantas: \`supportsReferences\` e \`maxReferences\` em \`action=models\`. Cada motor corta no próprio teto SEM erro (nano-banana-2 e Klein em 4, Grok em 3, Krea 2 da WaveSpeed em 1): mande as refs que importam primeiro. Use \`sapiens_reference\` pra achar a URL certa em vez de adivinhar.
 
 Nas Krea 2 da WaveSpeed a referência é a imagem-base (uma só), e \`refStrength\` diz quanto dela fica: 0.2 guarda a foto quase inteira, com o rosto; 0.45 guarda pose, roupa e fundo, e o prompt muda luz e clima; 0.65 (o default) guarda enquadramento e roupa, e rosto e cenário saem do prompt; 0.9 guarda só a proporção. A peça sai no formato da referência, não no \`aspectRatio\`. Pra segurar o rosto de personagem numa cena nova, o caminho é o Klein, não baixar a força.
 

package/dist/tools/image.js

@@ -23,7 +23,7 @@ const MODELS = [
     "flux-3-klein", // FLUX 3 Image Klein (BFL, pela fal) · o FLUX 3 leve, rápido e barato · COM refs (10 no catálogo, 5 pelo MCP) · adder até 2K · moderado, não é +18
     "krea-3", // Krea 3 (Krea, beta) · edita por referência e segura personagem · COM refs (8 no catálogo, 5 pelo MCP), CADA ref soma no preço · adder até 2K · moderado, não é +18
     "krea-3-high", // O MESMO Krea 3 com thinking high: planeja a edição antes, pra várias refs combinadas · mais caro e mais lento
-    // ByteDance via ModelArk direto. Corp/censurado, 2K nativo, COM refs (até 4).
+    // ByteDance via ModelArk direto. Corp/censurado, 2K nativo, COM refs (10 no catálogo, 5 pelo MCP).
     // (O "nova-canvas" ficava aqui e saiu: a AWS matou o modelo. Pedido antigo
     // ainda funciona, o backend faz o alias pro gpt-image-2-low.)
     "seedream-4-5", // Seedream 4.5 · cinematográfico
@@ -106,6 +106,8 @@ const DEFAULT_2K_MODELS = new Set([
     "nano-banana-max",
     "nano-banana-2",
 ]);
+/** Teto de referências somadas (urls + ids) que o servidor aceita numa chamada (MAX_REFERENCES do referenceResolver). */
+const MAX_REFS_PELO_MCP = 5;
 /** Tamanho padrão do motor, quando quem chama não passou o size. */
 function defaultSizeFor(model) {
     return model && DEFAULT_2K_MODELS.has(model) ? "2K" : undefined;
@@ -119,7 +121,7 @@ export const imageSchema = z.object({
     model: z
         .enum(MODELS)
         .optional()
-        .describe("Default 'nano-banana-2' (Nano Banana 2.1 com refs). 'nano-banana-max' (Pro 3) = qualidade alta. 'gpt-image-2-low/high' = GPT Image 2 nos tiers low e high. 'gpt-image-2-5-flare'/'gpt-image-2-5-sunburst' = GPT Image 2.5, a geração de set/2026, os dois em quality high e com referência: o Flare é o rápido, pra volume; o Sunburst é o de precisão, pra composição complexa e edição em várias voltas. 'mai-image-2-6' (MAI Image 2.6, da Microsoft) = foto rápida no mesmo recurso do gpt-image-2, e o único da casa que cobra por ÁREA: o adder de resolução aqui é real, o teto é 2K (1536², porque acima disso o provider recusa por total de pixels) e ele não aceita referência. 'muse-image' (Muse Image, da Meta) = barato na edição por referência e bom pra segurar personagem (10 refs no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls); sem escada de resolução (o motor decide o tamanho e cobra o mesmo) e moderação apertada, NÃO serve pra +18. 'flux-3' (FLUX 3, da Black Forest Labs) = texto na arte e composição precisos, aceita referência (10 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls), resolução até 2K; com referência a proporção segue a primeira imagem; moderado, NÃO serve pra +18. 'flux-3-klein' (FLUX 3 Image Klein, o irmão leve de pesos abertos do FLUX 3) = foto e personagem rápidos (~5 s) e baratos, aceita referência (10 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls) e segura a pessoa da ref numa cena nova, resolução até 2K; moderado, NÃO serve pra +18. 'krea-3' (Krea 3, da Krea, em beta) = edição por referência que SEGURA PERSONAGEM, inclusive anime e criatura com marcador no rosto, e foto com pele crua; aceita referência (8 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls), resolução até 2K. É o ÚNICO da casa que cobra cada referência à parte: o preço sobe por ref (o valor vivo sai em action=models), então mande só as refs que a cena precisa. Escreva em linguagem simples e chame cada referência pelo que ela mostra ('a primeira imagem é o rosto, a segunda o figurino'); pra edição, a mudança primeiro e uma frase de preservação no fim. 'krea-3-high' = o MESMO Krea 3 com thinking high: monta um plano de edição a partir do prompt e das refs antes de gerar; use quando combinar várias refs ou quando o 'krea-3' errou o pedido. Moderado, NÃO serve pra +18. 'seedream-4-5'/'seedream-5-0'/'seedream-5-0-pro' = ByteDance 2K nativo, cinematográfico, aceita até 4 referências (o 5.0 é a geração nova, entende prompt complexo melhor; o 5.0-pro é o topo da linha). 'grok-2-image'/'grok-2-image-quality' = xAI Grok Imagine da geração anterior (moderação frouxa +18, aceita refs e aspect; quality é mais fiel pra character lock); 'grok-imagine-2' = Grok Imagine Image 2.0, a geração nova de ago/2026, que é a melhor da linha integrando desenho e foto na mesma peça. DEGEN (uncensored, gate +18). NUDEZ É NÍVEL, NÃO MOTOR: três escolhas têm um par com nudez, e o par vem no campo `ousadia` de action=models. Sem nudez = o id da escolha; com nudez = o id do par + loraIntensity. Não existe motor '+18', 'Nu' ou 'Livre' separado pra procurar. 'wavespeed-chroma' (fotorrealista rápido, sem referência), 'wavespeed-flux2' (Flux.2 Klein Base: foto rápida, até 4 referências, segura o rosto) · com nudez = 'wavespeed-klein-nu' (o mesmo Klein com a LoRA de nudez no registro de foto; a identidade continua vindo da referência), 'wavespeed-klein-anime' (Flux.2 Klein + LoRA anime, inteligente e controlável) · com nudez = 'wavespeed-klein-anime-plus', 'wavespeed-flux-nsfw' (Flux dev + LoRA NSFW, sem par: a Ousadia é dele mesmo, via loraIntensity), 'wavespeed-klein-celular' (o MESMO Klein 9B com a LoRA Phone Photography por cima: foto de celular, candid, luz de janela; no edit com a referência da personagem o rosto fica quase idêntico, e é a receita de conteúdo de perfil de criadora pra personagem FOTOGRÁFICA. Em personagem cel-shaded o edit troca o traço, então não use com a Aria. Comece o prompt com 'This is a candid photograph taken with a smartphone of' e enumere 'same face, same hair' antes da cena; sem Ousadia), 'wavespeed-klein-transparencia' (o MESMO Klein 9B com a LoRA de tecido transparente: o efeito vem da LoRA e não da descrição; segura o rosto da ref; sem Ousadia), 'wavespeed-krea2-realism' (Krea 2 Realism: base 12B com LoRA de realismo, pele crua, hospedada na WaveSpeed SEM o classificador de entrada da fal, que devolve 422 até em prompt sem palavra de nudez; img2img de verdade com 1 referência, força regulável em refStrength, e 2K) · com nudez = 'wavespeed-krea2' (o mesmo realismo + LoRA NSFW; é a antiga 'Krea 2 Livre'), 'wavespeed-krea2-transparencia' (a mesma LoRA de transparência na base Krea 2: fotografia mais rica, identidade mais frouxa que a irmã Klein; 1 referência; sem Ousadia) = WaveSpeed rápido. LEGADO, fora da escolha da tela e ainda gerando pelo id (não ofereça): 'wavespeed-klein-plus' (a escolha virou 'wavespeed-klein-nu'), 'wavespeed-krea2-base' (Krea 2 sem LoRA nenhuma; a escolha virou 'wavespeed-krea2-realism'), 'fal-krea2-realism-v2' (Krea 2 Realism pela fal, ~4s: aceita até 3 referências de ESTILO, paleta/luz/textura de uma série, não character lock, e com referência a LoRA não vai junto; a escolha virou 'wavespeed-krea2-realism'). 'civitai-wai-illustrious'/'civitai-nova-anime-xl' (anime), 'civitai-pony-v6' (Pony V6 XL, base nº1) = Civitai sdcpp rápido. 'civitai-anima' (Anima: 2B da CircleStone com a Comfy Org, base própria e não SDXL; entrega anime de PRODUÇÃO, linha fechada e sombra chapada, em vez do registro de ilustração dos Illustrious. O encoder é um LLM, então escreva a cena em FRASE e não em tag booru, e não cole score_9/masterpiece aqui)."),
+        .describe("Default 'nano-banana-2' (Nano Banana 2.1 com refs). 'nano-banana-max' (Pro 3) = qualidade alta. 'gpt-image-2-low/high' = GPT Image 2 nos tiers low e high. 'gpt-image-2-5-flare'/'gpt-image-2-5-sunburst' = GPT Image 2.5, a geração de set/2026, os dois em quality high e com referência: o Flare é o rápido, pra volume; o Sunburst é o de precisão, pra composição complexa e edição em várias voltas. 'mai-image-2-6' (MAI Image 2.6, da Microsoft) = foto rápida no mesmo recurso do gpt-image-2, e o único da casa que cobra por ÁREA: o adder de resolução aqui é real, o teto é 2K (1536², porque acima disso o provider recusa por total de pixels) e ele não aceita referência. 'muse-image' (Muse Image, da Meta) = barato na edição por referência e bom pra segurar personagem (10 refs no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls); sem escada de resolução (o motor decide o tamanho e cobra o mesmo) e moderação apertada, NÃO serve pra +18. 'flux-3' (FLUX 3, da Black Forest Labs) = texto na arte e composição precisos, aceita referência (10 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls), resolução até 2K; com referência a proporção segue a primeira imagem; moderado, NÃO serve pra +18. 'flux-3-klein' (FLUX 3 Image Klein, o irmão leve de pesos abertos do FLUX 3) = foto e personagem rápidos (~5 s) e baratos, aceita referência (10 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls) e segura a pessoa da ref numa cena nova, resolução até 2K; moderado, NÃO serve pra +18. 'krea-3' (Krea 3, da Krea, em beta) = edição por referência que SEGURA PERSONAGEM, inclusive anime e criatura com marcador no rosto, e foto com pele crua; aceita referência (8 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls), resolução até 2K. É o ÚNICO da casa que cobra cada referência à parte: o preço sobe por ref (o valor vivo sai em action=models), então mande só as refs que a cena precisa. Escreva em linguagem simples e chame cada referência pelo que ela mostra ('a primeira imagem é o rosto, a segunda o figurino'); pra edição, a mudança primeiro e uma frase de preservação no fim. 'krea-3-high' = o MESMO Krea 3 com thinking high: monta um plano de edição a partir do prompt e das refs antes de gerar; use quando combinar várias refs ou quando o 'krea-3' errou o pedido. Moderado, NÃO serve pra +18. 'seedream-4-5'/'seedream-5-0'/'seedream-5-0-pro' = ByteDance 2K nativo, cinematográfico, aceita referência (10 no catálogo; pelo MCP vale o teto de 5 do campo referenceImageUrls) (o 5.0 é a geração nova, entende prompt complexo melhor; o 5.0-pro é o topo da linha). 'grok-2-image'/'grok-2-image-quality' = xAI Grok Imagine da geração anterior (moderação frouxa +18, aceita refs e aspect; quality é mais fiel pra character lock); 'grok-imagine-2' = Grok Imagine Image 2.0, a geração nova de ago/2026, que é a melhor da linha integrando desenho e foto na mesma peça. Daqui em diante, a LINHA DEGEN (sem freio de conteúdo, gate +18; o Grok fica fora dela). NUDEZ É NÍVEL, NÃO MOTOR: três escolhas têm um par com nudez, e o par vem no campo `ousadia` de action=models. Sem nudez = o id da escolha; com nudez = o id do par + loraIntensity. Não existe motor '+18', 'Nu' ou 'Livre' separado pra procurar. 'wavespeed-chroma' (fotorrealista rápido, sem referência), 'wavespeed-flux2' (Flux.2 Klein Base: foto rápida, até 4 referências, segura o rosto) · com nudez = 'wavespeed-klein-nu' (o mesmo Klein com a LoRA de nudez no registro de foto; a identidade continua vindo da referência), 'wavespeed-klein-anime' (Flux.2 Klein + LoRA anime, inteligente e controlável) · com nudez = 'wavespeed-klein-anime-plus', 'wavespeed-flux-nsfw' (Flux dev + LoRA NSFW, sem par: a Ousadia é dele mesmo, via loraIntensity), 'wavespeed-klein-celular' (o MESMO Klein 9B com a LoRA Phone Photography por cima: foto de celular, candid, luz de janela; no edit com a referência da personagem o rosto fica quase idêntico, e é a receita de conteúdo de perfil de criadora pra personagem FOTOGRÁFICA. Em personagem cel-shaded o edit troca o traço, então não use com a Aria. Comece o prompt com 'This is a candid photograph taken with a smartphone of' e enumere 'same face, same hair' antes da cena; sem Ousadia), 'wavespeed-klein-transparencia' (o MESMO Klein 9B com a LoRA de tecido transparente: o efeito vem da LoRA e não da descrição; segura o rosto da ref; sem Ousadia), 'wavespeed-krea2-realism' (Krea 2 Realism: base 12B com LoRA de realismo, pele crua, hospedada na WaveSpeed SEM o classificador de entrada da fal, que devolve 422 até em prompt sem palavra de nudez; img2img de verdade com 1 referência, força regulável em refStrength, e 2K) · com nudez = 'wavespeed-krea2' (o mesmo realismo + LoRA NSFW; é a antiga 'Krea 2 Livre'), 'wavespeed-krea2-transparencia' (a mesma LoRA de transparência na base Krea 2: fotografia mais rica, identidade mais frouxa que a irmã Klein; 1 referência; sem Ousadia) = WaveSpeed rápido. LEGADO, fora da escolha da tela e ainda gerando pelo id (não ofereça): 'wavespeed-klein-plus' (a escolha virou 'wavespeed-klein-nu'), 'wavespeed-krea2-base' (Krea 2 sem LoRA nenhuma; a escolha virou 'wavespeed-krea2-realism'), 'fal-krea2-realism-v2' (Krea 2 Realism pela fal, ~4s: aceita até 3 referências de ESTILO, paleta/luz/textura de uma série, não character lock, e com referência a LoRA não vai junto; a escolha virou 'wavespeed-krea2-realism'). 'civitai-wai-illustrious'/'civitai-nova-anime-xl' (anime), 'civitai-pony-v6' (Pony V6 XL, base nº1) = Civitai sdcpp rápido. 'civitai-anima' (Anima: 2B da CircleStone com a Comfy Org, base própria e não SDXL; entrega anime de PRODUÇÃO, linha fechada e sombra chapada, em vez do registro de ilustração dos Illustrious. O encoder é um LLM, então escreva a cena em FRASE e não em tag booru, e não cole score_9/masterpiece aqui)."),
     aspectRatio: z
         .enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"])
         .optional()
@@ -131,12 +133,12 @@ export const imageSchema = z.object({
     styleId: z
         .string()
         .optional()
-        .describe("Default 'none'. IDs de estilo no convex/shared/imageStyles.ts."),
+        .describe("Legado, sem efeito: o servidor não lê este campo. Estilo vem de brandSlug, templateSlug ou registro."),
     negativePrompt: z.string().optional(),
     referenceImageUrls: z
         .array(httpUrl())
         .optional()
-        .describe("URLs públicas de referência pra combinar numa geração só (character/style lock), igual ao modal 'Selecionar Referência' do gerador web. Fontes: sua galeria (sapiens_gallery, campo url), o Acervo, e personagens públicos (sapiens_character action=list_public → mainImageUrl/imageUrls). Restrito a hosts do Sapiens (Bunny CDN / Convex) + Wikimedia. Requer model com refs (o campo supportsReferences em action=models é a fonte): nano-banana-*, gpt-image-2-*, muse-image, flux-3, flux-3-klein, krea-3 e krea-3-high (cada ref soma no preço), seedream-*, grok-* (até 3), a família Klein (wavespeed-flux2 e wavespeed-klein-*, até 4), wavespeed-flux-nsfw (1), a família Krea 2 da WaveSpeed (wavespeed-krea2-realism, wavespeed-krea2 e wavespeed-krea2-transparencia; img2img: a primeira referência vira a imagem-base, 1 ref, e refStrength diz quanto dela fica) ou fal-krea2-* (referência de ESTILO, teto de 3). Soma com sourceImageIds: até 5 no total (acima disso o servidor recusa a chamada), e cada motor corta no seu teto quando ele é menor (Seedream 4, Klein 4, Grok 3, Krea 2 e Flux NSFW 1; o campo maxReferences em action=models é a fonte)."),
+        .describe("URLs públicas de referência pra combinar numa geração só (character/style lock), igual ao modal 'Selecionar Referência' do gerador web. Fontes: sua galeria (sapiens_gallery, campo url), o Acervo, e personagens públicos (sapiens_character action=list_public → mainImageUrl/imageUrls). Restrito a hosts do Sapiens (Bunny CDN / Convex) + Wikimedia. Requer model com refs (o campo supportsReferences em action=models é a fonte): nano-banana-*, gpt-image-2-*, muse-image, flux-3, flux-3-klein, krea-3 e krea-3-high (cada ref soma no preço), seedream-*, grok-* (até 3), a família Klein (wavespeed-flux2 e wavespeed-klein-*, até 4), wavespeed-flux-nsfw (1), a família Krea 2 da WaveSpeed (wavespeed-krea2-realism, wavespeed-krea2 e wavespeed-krea2-transparencia; img2img: a primeira referência vira a imagem-base, 1 ref, e refStrength diz quanto dela fica) ou fal-krea2-* (referência de ESTILO, teto de 3). Soma com sourceImageIds: até 5 no total (acima disso o servidor recusa a chamada), e cada motor corta no seu teto quando ele é menor, SEM erro: a ref a mais some (nano-banana-2 e Klein 4, Grok 3, Krea 2 da WaveSpeed e Flux NSFW 1; o campo maxReferences em action=models é a fonte)."),
     sourceImageIds: z
         .array(z.string())
         .optional()
@@ -264,6 +266,14 @@ export async function image(args) {
             // resolução. null = referência não muda o preço.
             referenceAdders: m.referencePriceSinapses ?? null,
             supportsReferences: !!m.supportsReferences,
+            // Quantas referências chegam ao motor PELO MCP: o teto do motor no
+            // catálogo (ausente = 4, o DEFAULT_MAX_REFERENCES do servidor) cortado
+            // no teto de 5 do resolvedor. As descrições de referenceImageUrls e
+            // sourceImageIds mandam olhar este campo, que até a 1.103 não existia:
+            // a 5ª ref no nano-banana-2 sumia sem aviso. 0 = não aceita referência.
+            maxReferences: m.supportsReferences
+                ? Math.min(typeof m.maxReferences === "number" ? m.maxReferences : 4, MAX_REFS_PELO_MCP)
+                : 0,
             degen: /^(civitai-|wavespeed-|fal-)/.test(String(m.id)),
             // O id que gera esta mesma escolha COM nudez (manda junto loraIntensity).
             // null = sem par; se o próprio motor tem LoRA tunável, a Ousadia é dele.
@@ -297,7 +307,8 @@ export async function image(args) {
             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]. Sem size, nano-banana-* e a família Krea 2 geram em 2K (somam o adder de 2K); o valor debitado volta em custoSinapses no generate. degen=+18 (gate na galeria). " +
+                "maxReferences é quantas referências chegam ao motor por aqui (o teto dele, cortado em 5): a mais, somem sem erro. " +
                 "Quando referenceAdders vem preenchido (Krea 3), cada referência soma referenceAdders[size] ao preço, até o teto do motor. " +
                 "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. " +
                 "Nudez é nível, não motor: quando `ousadia` vem preenchido, gere com ousadia.model + loraIntensity pra ter nudez e com o id da linha pra não ter (o preço com nudez vem em ousadia.priceSinapses).",
@@ -423,6 +434,9 @@ export async function image(args) {
         ...(args.transparentBackground === true ? { transparentBackground: true } : {}),
         // Pago com o saldo em dólar da API: quanto saiu. Ausente quando foi em Sinapses.
         ...(typeof result?.pagoEmDolarUsd === "number" ? { pagoEmDolarUsd: result.pagoEmDolarUsd } : {}),
+        // Pago em Sinapses: o que o extrato debitou (resolução, refs pagas e
+        // override já dentro). Backend de antes do campo não manda, e aí não vem.
+        ...(typeof result?.custoSinapses === "number" ? { custoSinapses: result.custoSinapses } : {}),
         // Não incluir base64 no retorno (polui contexto). Quem quiser bytes
         // chama sapiens_gallery action=get com includeBase64=true.
     };

package/dist/tools/reference.js

@@ -22,6 +22,10 @@ import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
  *   - characters personagens; `mode` = 'mine' (default) ou 'public'
  *   - depth map guias de movimento; `shadowSource` = 'house' (banco curado, default) ou 'mine'
  *
+ * `semantic` lê o `term` como descrição e busca por SIGNIFICADO em history,
+ * videos (creationEmbeddings) e pose_map (poseRefs): a prateleira "Pelo
+ * sentido" do picker web, por outra porta porque vetor não pagina como lista.
+ *
  * Cada item volta normalizado:
  *   - imagem PRÓPRIA (history/favorites): `imageId` + `url` → use imageId em
  *     sourceImageIds / startImageId / endImageId, ou url em referenceImageUrls.
@@ -41,11 +45,11 @@ export const referenceSchema = z.object({
         // proíbe quebrar quem está atrasado. O servidor aceita os dois.
         .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), " +
+        .describe("Só 'browse': qual banco navegar: 'history' (suas imagens recentes; com term+semantic acha pelo significado), " +
+        "'favorites' (as que você curtiu), 'videos' (seus vídeos; idem), '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), " +
-        "'pose_map' (seu banco privado de POSE: mapa de profundidade de corpo num quadro parado, aceita term/orientation/people/hasObject/objeto/favoritesOnly/collection/sort, mais semantic e similarTo pra busca por sentido)."),
+        "'pose_map' (seu banco privado de POSE: mapa de profundidade de corpo num quadro parado, quase 7 mil poses organizadas por familia/vista/enquadramento/leitura; aceita também term/orientation/people/hasObject/hasSuporte/objeto/favoritesOnly/collection/sort, mais semantic e similarTo pra busca por sentido)."),
     handle: z
         .string()
         .optional()
@@ -111,9 +115,11 @@ export const referenceSchema = z.object({
     semantic: z
         .boolean()
         .optional()
-        .describe("Só bucket 'pose_map': lê o `term` como DESCRIÇÃO da cena em vez de palavra-chave. " +
-        "É o caminho pra pedido que nenhuma tag cobre ('alguém se protegendo do vento', " +
-        "'caindo de costas apoiado num braço'). Frase inteira funciona melhor que palavra solta."),
+        .describe("Buckets 'history', 'videos' e 'pose_map': lê o `term` como DESCRIÇÃO em vez de palavra-chave, e acha " +
+        "pelo SIGNIFICADO. Em history/videos acha a peça da pessoa mesmo quando o prompt usou outras palavras " +
+        "('praia ao entardecer' acha 'golden hour beach'); em pose_map, o pedido que nenhuma tag cobre " +
+        "('alguém se protegendo do vento', 'caindo de costas apoiado num braço'). Frase inteira funciona melhor " +
+        "que palavra solta. Sem paginação: volta até `limit` (máx 50), do mais parecido pro menos, com `score`."),
     similarTo: z
         .string()
         .optional()
@@ -123,6 +129,41 @@ export const referenceSchema = z.object({
         .enum(["recent", "used"])
         .optional()
         .describe("Só bucket 'pose_map': 'recent' (entrada no banco, default) ou 'used' (as que ele acabou de usar, mais úteis pra continuar uma série)."),
+    // As categorias do pose_map. Os ids espelham apps/sapiens/convex/shared/poseTaxonomia.js
+    // (fonte única; o teste convex/shared/poseTaxonomia.test.ts trava a paridade).
+    familia: z
+        .enum([
+        "em-pe",
+        "em-movimento",
+        "inclinada",
+        "agachada",
+        "ajoelhada",
+        "sentada",
+        "deitada",
+        "quatro-apoios",
+        "no-ar",
+        "invertida",
+    ])
+        .optional()
+        .describe("Só bucket 'pose_map': o que o corpo faz, a categoria principal do banco (lida por visão, não pela tag do esqueleto). " +
+        "'em-movimento' = passada, corrida, chute, giro; 'inclinada' = em pé com o tronco dobrado; 'no-ar' = salto, queda, pendurada; " +
+        "'invertida' = de cabeça pra baixo. Combina com vista e com semantic."),
+    vista: z
+        .enum(["frente", "tres-quartos", "perfil", "costas"])
+        .optional()
+        .describe("Só bucket 'pose_map': de onde a câmera vê o corpo. 'costas' inclui três quartos de costas: a fronteira é peito ou costas pra câmera, que a sombra sem rosto não diz sozinha."),
+    enquadramento: z
+        .enum(["corpo-inteiro", "joelhos", "cintura", "busto"])
+        .optional()
+        .describe("Só bucket 'pose_map': até onde o quadro mostra o corpo."),
+    leitura: z
+        .enum(["clara", "confusa"])
+        .optional()
+        .describe("Só bucket 'pose_map': 'clara' = a sombra se entende sozinha. 'confusa' = membro fundido, escondido ou cortado, a sombra que devolve braço sem dono ou duas pernas esquerdas. Pra gerar personagem, prefira 'clara'."),
+    hasSuporte: z
+        .boolean()
+        .optional()
+        .describe("Só bucket 'pose_map': true = só poses apoiadas em algo além do chão (banco, bloco, parede, cama: vem em `suporte`); false = só no chão. Omitir = as duas."),
     mode: z
         .enum(["mine", "public"])
         .optional()
@@ -165,6 +206,9 @@ export async function reference(args) {
                 similarTo: args.similarTo,
                 people: args.people,
                 limit: args.limit,
+                familia: args.familia,
+                vista: args.vista,
+                leitura: args.leitura,
             });
             const itens = res?.items ?? [];
             return {
@@ -175,11 +219,51 @@ export async function reference(args) {
                 note: itens.length
                     ? "Vizinhança por SENTIDO, da mais parecida pra menos (`score` é a distância). " +
                         "Cada item traz `descricao`: leia antes de escolher, é ela que diz o que o corpo faz. " +
-                        "Use a `url` em sapiens_image referenceImageUrls."
+                        "Use a `url` em sapiens_image referenceImageUrls e cole `membros` no prompt (lado de cada braço e perna). " +
+                        "`usadaPor` diz quem já usou a pose: não repita na mesma personagem."
                     : "Nenhuma pose do seu banco chegou perto disso. Tente descrever o CORPO (apoio, direção do tronco, " +
                         "o que os braços fazem) em vez da cena, ou use browse com people/hasObject.",
             };
         }
+        // A mesma porta de sentido pras SUAS imagens e vídeos (creationEmbeddings):
+        // o `term` vira vetor e volta a vizinhança, no shape dos itens do browse.
+        if ((args.bucket === "history" || args.bucket === "videos") && args.semantic && args.term?.trim()) {
+            const video = args.bucket === "videos";
+            const res = await convexAction("creationEmbeddings:mcpSearchByMeaning", {
+                sessionToken,
+                term: args.term,
+                type: video ? "VIDEO" : "IMAGE",
+                limit: args.limit,
+            });
+            const itens = (res?.items ?? []).map((r) => ({
+                refKind: video ? "video" : "image",
+                imageId: r.imageId,
+                url: r.url,
+                thumbnailUrl: r.posterUrl ?? null,
+                title: r.seoTitle ?? null,
+                prompt: r.prompt ?? null,
+                model: r.model ?? null,
+                aspectRatio: r.aspectRatio ?? null,
+                isPublic: !!r.isPublic,
+                createdAt: r.createdAt ?? null,
+                source: args.bucket,
+                score: r.score,
+            }));
+            return {
+                bucket: args.bucket,
+                modo: "sentido",
+                count: itens.length,
+                items: itens,
+                note: itens.length
+                    ? "Peças SUAS por significado, da mais parecida pra menos (`score`). " +
+                        (video
+                            ? "Cada item é um vídeo seu (imageId reusável em sapiens_video)."
+                            : "Use o imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId, ou a url em referenceImageUrls.")
+                    : `Nada do seu acervo chegou perto de "${args.term}" por significado. Tente descrever o que aparece na ` +
+                        "peça, ou browse com o mesmo `term` sem semantic (pedaço de palavra). Peça muito recente pode ainda " +
+                        "não estar no índice: ela entra alguns segundos depois de pronta.",
+            };
+        }
         const res = await convexAction("mcpReferences:referenceBrowse", {
             sessionToken,
             bucket: args.bucket,
@@ -197,6 +281,11 @@ export async function reference(args) {
             favoritesOnly: args.favoritesOnly,
             collection: args.collection,
             sort: args.sort,
+            familia: args.familia,
+            vista: args.vista,
+            enquadramento: args.enquadramento,
+            leitura: args.leitura,
+            hasSuporte: args.hasSuporte,
         });
         let note;
         if (args.bucket === "videos") {
@@ -213,7 +302,7 @@ export async function reference(args) {
         }
         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. Cada item diz `people` (solo/dupla/grupo), `objeto` (null = corpo limpo), `favorite` e `useCount`; pra recortar, mande people/hasObject/objeto em vez de tentar pela busca escrita. Pedido vago ('uma pose boa pra isso') começa por favoritesOnly=true ou sort='used': é a curadoria que o dono já fez, e ela vale mais que mil opções. `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.";
+                "Poses do SEU banco privado (mapa de profundidade de corpo). Use a `url` (a SOMBRA pura) em sapiens_image referenceImageUrls pra guiar a POSE da figura, com a linha 'adopt exactly the body pose of the <n>th reference; it is a pose guide only, ignore its grey tones'. Cada item traz `familia`, `vista`, `enquadramento` e `leitura` (prefira 'clara': a 'confusa' devolve membro sem dono), `people`, `objeto` (o que a mão segura), `suporte` (banco, bloco, parede: nomeie no prompt onde o corpo se apoia), `descricao` e `membros` (cada braço e perna com o LADO da pessoa, em inglês: cole no prompt, é o que evita duas pernas esquerdas). `skeletonUrl` é a SOMA (sombra + esqueleto colorido), guia OPCIONAL: em imagem, a sombra pura + `membros` no prompt já dizem o lado de cada membro e não deixam marca; a soma só vale quando a pose é difícil de ler, sempre com 'ignore any coloured overlay lines', e confira a peça, porque o traço às vezes fica na imagem (em VÍDEO a soma ganhou da sombra no A/B da casa). `usadaPor` diz quem já usou: não repita a pose na mesma personagem. Pra recortar, mande familia/vista/leitura/people/hasObject/hasSuporte em vez de tentar pela busca escrita; `poseId` vai em similarTo pra variações do mesmo gesto. Pedido vago ('uma pose boa pra isso') começa por favoritesOnly=true ou sort='used': é a curadoria que o dono já fez. É 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 =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.101.0",
+  "version": "1.102.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. mcprush.com-bd2545268b8471cdb213c674",
   "type": "module",