sapiens_image
Generate and edit AI images using multiple models, combining up to 4 reference images for character/style lock. List model options, request video generation, and compose Shorts frames.
Instructions
Operações de imagem via Sapiens (Gemini, Azure gpt-image-2, Grok, Veo). Sub-actions: '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), 'request_generation' (cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo. 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 atual com override admin + maxResolution + se aceita referência) pra descobrir modelo/preço em vez de chutar. 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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Default 'create' (gera do zero). 'edit' aplica prompt como mudança sobre sourceImageId. 'variation' gera similar mantendo estilo. Edit/variation exigem sourceImageId e enviam a imagem como referência inline pro modelo. | |
| size | No | Default '1K'. Adder de resolução só nos modelos com hasResolutionAdder: nano-banana-max e nano-banana-2 aceitam 2K (+100) e 4K (+300); grok-2-image e grok-2-image-quality aceitam só 2K (+100), sem 4K. Nos demais modelos o size é ignorado (fica em 1K). | |
| model | No | Default 'nano-banana-2' (Flash 3.1 com refs). 'nano-banana-max' (Pro 3) = qualidade alta. 'gpt-image-2-low/high' = Azure. 'grok-2-image'/'grok-2-image-quality' = xAI Grok Imagine (moderação frouxa +18, aceita refs e aspect; quality é mais fiel pra character lock). DEGEN (uncensored, gate +18): 'wavespeed-chroma' (fotorrealista rápido), 'wavespeed-flux2' (Flux.2 Klein), 'wavespeed-flux-nsfw' (flux+LoRA NSFW, Ousadia regulável via loraIntensity), 'wavespeed-klein-anime' (Flux.2 Klein + LoRA anime, inteligente+controlável), 'wavespeed-klein-anime-plus' (Klein anime +18, Ousadia regulável) = WaveSpeed rápido; 'civitai-wai-illustrious'/'civitai-nova-anime-xl' (anime), 'civitai-pony-v6' (Pony V6 XL, base nº1) = Civitai sdcpp rápido. 'fal-krea2-realism'/'fal-krea2-realism-v2' (Krea-2 Turbo 12B + LoRA de realismo, fal.ai, ~4s, fotorrealismo forte) = SÓ txt2img (não aceita referência). | |
| action | Yes | ||
| prompt | No | Prompt da imagem (obrigatório em generate/request_generation). Full-bleed, sujeito oversized. | |
| styleId | No | Default 'none'. IDs de estilo no convex/shared/imageStyles.ts. | |
| brandMark | No | Marca na imagem do brand: 'persona' (personagem do brand via character sheets, ex: Helen), 'logo' (carimba a logo no canto), 'none' (só o estilo). Default 'none'. Só aplica se brandSlug setado e o brand oferecer a marca. | |
| brandSlug | No | Slug do brand (design system) pra aplicar estilo visual. Fonte única: tabela `brands` (ex: 'sapiens', 'solarpunk', 'editorial-duotone', 'brutalista-mono'). Default: nenhum (prompt cru). Vale em action=generate (mode=create) e request_generation. | |
| useStudio | No | Quando true, gera SEGUINDO o studio do user (o 'Meu Studio', ÚNICO, resolvido pela sessão — você NÃO passa id): marca + personagem-operador + a vibe + os presets do bloco de imagem entram sozinhos (o explícito sempre vence). O retorno traz studioApplied: true se aplicou o studio, false se caiu no Sapiens base (sem studio montado — aí avise o user). É o 'criar no meu studio' do Nível 2, e gerar assim faz o studio evoluir. SEM useStudio = geração base, fora da identidade dele: não misture. Cheque o studio com sapiens_studios action=mine. Vale em action=generate. | |
| aspectRatio | No | Default '1:1'. 9:16 = vertical pra story/short, 16:9 = landscape. | |
| instruction | No | Pra action=compose: instrução em EN pro Gemini. Ex: 'Compose a vertical 9:16 photo: persona holding a smartphone facing the camera, the phone screen displaying the provided second image (clearly visible, sharp). Mobile photography aesthetic.' | |
| influencerId | No | ID de personagem (influencer) pra character-lock. Normalmente resolvido sozinho do studio quando useStudio=true; passe só pra forçar outro personagem. | |
| templateSlug | No | Slug de um template de imagem (super-prompt travado da casa). Quando setado, o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha com o estilo + fundo + enquadramento + ref de traço da casa. Ex: 'retrato-sapiens-v1' = retrato editorial cartoon de UM personagem no grid verde Sapiens (mesma 'mão' dos artigos). O template define model/aspect/size default (sobreponíveis) e injeta a ref da Helen como âncora de traço quando você não passa referenceImageUrls própria (passar refs = trocar quem aparece, mantendo o estilo). Mutuamente exclusivo com brandSlug. Vale em action=generate, mode=create. | |
| loraIntensity | No | Ousadia da LoRA regulável, SÓ nos modelos com LoRA tunável ('wavespeed-flux-nsfw' e 'wavespeed-klein-anime-plus'): suave=insinua sem despir, medio=maduro no limite (default), forte=sem freio. Ideal pra remixar personagem (ex: a Helen) preservando a identidade e regulando a liberdade. Ignorado nos demais modelos. | |
| personaBase64 | No | Pra action=compose: base64 da imagem persona (start ref). 1 dos {personaBase64, screenImage*} obrigatório. | |
| sourceImageId | No | ID de imagem do gallery do próprio user (`generatedImages:_id`). Obrigatório pra mode=edit ou mode=variation. Use sapiens_gallery action=list pra descobrir IDs. | |
| negativePrompt | No | ||
| screenImageUrl | No | Pra action=compose: URL da tela (Bunny CDN). Convex baixa server-side. | |
| sourceImageIds | No | Até 4 IDs de imagens da SUA galeria (`generatedImages:_id` via sapiens_gallery) usadas como referência. Alternativa por-id ao referenceImageUrls pras suas próprias imagens (ownership checado). Soma com referenceImageUrls (teto total de 4). | |
| personaMimeType | No | ||
| screenImageBase64 | No | Pra action=compose: base64 da tela. Alt: screenImageUrl. | |
| referenceImageUrls | No | Até 4 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: nano-banana-2, gpt-image-2-* ou grok-2-image*. Soma com sourceImageIds (teto total de 4). | |
| screenImageMimeType | No |