# # Licenciado sob a Apache License, Versão 2.0 (a "Licença"); # você não pode usar este arquivo, exceto em conformidade com a Licença. # Você pode obter uma cópia da Licença em # # http://www.apache.org/licenses/LICENSE-2.0 # # A menos que exigido pela lei aplicável ou acordado por escrito, o software # distribuído sob a Licença é distribuído em uma base "COMO ESTÁ", # SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas. # Consulte a Licença para o idioma específico que rege as permissões e # limitações sob a Licença. --> # Sana-Video [SANA-Video: Efficient Video Generation with Block Linear Diffusion Transformer](https://huggingface.co/papers/2509.24695) da NVIDIA e do MIT HAN Lab, por Junsong Chen, Yuyang Zhao, Jincheng Yu, Ruihang Chu, Junyu Chen, Shuai Yang, Xianbang Wang, Yicheng Pan, Daquan Zhou, Huan Ling, Haozhe Liu, Hongwei Yi, Hao Zhang, Muyang Li, Yukang Chen, Han Cai, Sanja Fidler, Ping Luo, Song Han, Enze Xie. O resumo do artigo é: *Apresentamos o SANA-Video, um pequeno modelo de difusão capaz de gerar vídeos de forma eficiente, com resolução de até 720x1280 e duração de até um minuto. O SANA-Video sintetiza vídeos de alta resolução, alta qualidade e longa duração, com forte alinhamento entre texto e vídeo, a uma velocidade notavelmente rápida, podendo ser implantado em GPU RTX 5090. Dois designs centrais garantem a geração de vídeos eficiente, eficaz e longa: (1) Linear DiT: utilizamos a atenção linear como operação central, que é mais eficiente que a atenção convencional, dado o grande número de tokens processados na geração de vídeos. (2) Cache KV de memória constante para Block Linear Attention: projetamos uma abordagem autoregressiva por blocos para a geração de vídeos longos, empregando um estado de memória constante, derivado das propriedades cumulativas da atenção linear. Esse cache KV fornece ao Linear DiT contexto global a um custo de memória fixo, eliminando a necessidade de um cache KV tradicional e permitindo a geração eficiente de vídeos de longa duração. Além disso, exploramos filtros de dados eficazes e estratégias de treinamento do modelo, reduzindo o custo de treinamento para 12 dias em 64 GPUs H100, o que representa apenas 1% do custo do MovieGen. Dado seu baixo custo, o SANA-Video alcança desempenho competitivo em comparação com modelos de difusão pequenos e modernos do estado da arte (por exemplo, Wan 2.1-1.3B e SkyReel-V2-1.3B), sendo 16x mais rápido em latência medida. Além disso, o SANA-Video pode ser implantado em GPUs RTX 5090 com precisão NVFP4, acelerando a velocidade de inferência para a geração de um vídeo 720p de 5 segundos de 71s para 29s (aceleração de 2.4x). Em resumo, o SANA-Video permite a geração de vídeos de alta qualidade a baixo custo. [este URL https](https://github.com/NVlabs/SANA).* Este pipeline foi contribuído pela equipe SANA. A base de código original pode ser encontrada [aqui](https://github.com/NVlabs/Sana). Os pesos originais podem ser encontrados em [hf.co/Efficient-Large-Model](https://hf.co/collections/Efficient-Large-Model/sana-video). Modelos disponíveis: | Model | dtype recomendado | |:-----:|:-----------------:| | [`Efficient-Large-Model/SANA-Video_2B_480p_diffusers`](https://huggingface.co/Efficient-Large-Model/ANA-Video_2B_480p_diffusers) | `torch.bfloat16` | Consulte esta [coleção](https://huggingface.co/collections/Efficient-Large-Model/sana-video) para mais informações. Nota: O dtype recomendado mencionado é para os pesos do transformer. Os pesos do codificador de texto e do VAE devem permanecer em `torch.bfloat16` ou `torch.float32` para que o modelo funcione corretamente. Consulte o exemplo de inferência abaixo para ver como carregar o modelo com o dtype recomendado. ## Pipelines de Geração ` O exemplo abaixo demonstra como usar o pipeline de texto para vídeo para gerar um vídeo usando uma descrição de texto. ```python pipe = SanaVideoPipeline.from_pretrained( "Efficient-Large-Model/SANA-Video_2B_480p_diffusers", dtype=torch.bfloat16, ) pipe.text_encoder.to(torch.bfloat16) pipe.vae.to(torch.float32) pipe.to("cuda") # or "mps", "xpu", "cpu" prompt = "A cat and a dog baking a cake together in a kitchen. The cat is carefully measuring flour, while the dog is stirring the batter with a wooden spoon. The kitchen is cozy, with sunlight streaming through the window." negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience." motion_scale = 30 motion_prompt = f" motion score: {motion_scale}." prompt = prompt + motion_prompt video = pipe( prompt=prompt, negative_prompt=negative_prompt, height=480, width=832, frames=81, guidance_scale=6, num_inference_steps=50, generator=torch.Generator(device="cuda").manual_seed(0), ).frames[0] export_to_video(video, "sana_video.mp4", fps=16) ``` O exemplo abaixo demonstra como usar o pipeline de imagem para vídeo para gerar um vídeo usando uma descrição de texto e um quadro inicial. ```python pipe = SanaImageToVideoPipeline.from_pretrained( "Efficient-Large-Model/SANA-Video_2B_480p_diffusers", dtype=torch.bfloat16, ) pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, flow_shift=8.0) pipe.vae.to(torch.float32) pipe.text_encoder.to(torch.bfloat16) pipe.to("cuda") # or "mps", "xpu", "cpu" image = load_image("https://raw.githubusercontent.com/NVlabs/Sana/refs/heads/main/asset/samples/i2v-1.png") prompt = "A woman stands against a stunning sunset backdrop, her long, wavy brown hair gently blowing in the breeze. She wears a sleeveless, light-colored blouse with a deep V-neckline, which accentuates her graceful posture. The warm hues of the setting sun cast a golden glow across her face and hair, creating a serene and ethereal atmosphere. The background features a blurred landscape with soft, rolling hills and scattered clouds, adding depth to the scene. The camera remains steady, capturing the tranquil moment from a medium close-up angle." negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience." motion_scale = 30 motion_prompt = f" motion score: {motion_scale}." prompt = prompt + motion_prompt motion_scale = 30.0 video = pipe( image=image, prompt=prompt, negative_prompt=negative_prompt, height=480, width=832, frames=81, guidance_scale=6, num_inference_steps=50, generator=torch.Generator(device="cuda").manual_seed(0), ).frames[0] export_to_video(video, "sana-i2v.mp4", fps=16) ``` ## Quantização A quantização ajuda a reduzir os requisitos de memória de modelos muito grandes armazenando os pesos do modelo em um tipo de dados de menor precisão. No entanto, a quantização pode ter um impacto variável na qualidade do vídeo, dependendo do modelo de vídeo. Consulte a visão geral de [Quantization](../../quantization/overview) para saber mais sobre os backends de quantização suportados e sobre como selecionar um backend de quantização que atenda ao seu caso de uso. O exemplo abaixo demonstra como carregar um [SanaVideoPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/sana_video#diffusers.SanaVideoPipeline) quantizado para inferência com bitsandbytes. ```py import torch from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, SanaVideoTransformer3DModel, SanaVideoPipeline from transformers import BitsAndBytesConfig as BitsAndBytesConfig, AutoModel quant_config = BitsAndBytesConfig(load_in_8bit=True) text_encoder_8bit = AutoModel.from_pretrained( "Efficient-Large-Model/SANA-Video_2B_480p_diffusers", subfolder="text_encoder", quantization_config=quant_config, dtype=torch.float16, ) quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True) transformer_8bit = SanaVideoTransformer3DModel.from_pretrained( "Efficient-Large-Model/SANA-Video_2B_480p_diffusers", subfolder="transformer", quantization_config=quant_config, dtype=torch.float16, ) pipeline = SanaVideoPipeline.from_pretrained( "Efficient-Large-Model/SANA-Video_2B_480p_diffusers", text_encoder=text_encoder_8bit, transformer=transformer_8bit, dtype=torch.float16, device_map="balanced", ) model_score = 30 prompt = "Evening, backlight, side lighting, soft light, high contrast, mid-shot, centered composition, clean solo shot, warm color. A young Caucasian man stands in a forest, golden light glimmers on his hair as sunlight filters through the leaves. He wears a light shirt, wind gently blowing his hair and collar, light dances across his face with his movements. The background is blurred, with dappled light and soft tree shadows in the distance. The camera focuses on his lifted gaze, clear and emotional." negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience." motion_prompt = f" motion score: {model_score}." prompt = prompt + motion_prompt output = pipeline( prompt=prompt, negative_prompt=negative_prompt, height=480, width=832, num_frames=81, guidance_scale=6.0, num_inference_steps=50 ).frames[0] export_to_video(output, "sana-video-output.mp4", fps=16) ``` ## SanaVideoPipeline[[diffusers.SanaVideoPipeline]] #### diffusers.SanaVideoPipeline[[diffusers.SanaVideoPipeline]] ```python diffusers.SanaVideoPipeline(tokenizer: GemmaTokenizer, text_encoder: Gemma2PreTrainedModel, vae: diffusers.models.autoencoders.autoencoder_dc.AutoencoderDC | diffusers.models.autoencoders.autoencoder_kl_ltx2.AutoencoderKLLTX2Video | diffusers.models.autoencoders.autoencoder_kl_wan.AutoencoderKLWan, transformer: SanaVideoTransformer3DModel, scheduler: DPMSolverMultistepScheduler) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video.py#L186) **Parâmetros:** tokenizer (`GemmaTokenizer` ou `GemmaTokenizerFast`) : O tokenizador usado para tokenizar o prompt. text_encoder (`Gemma2PreTrainedModel`) : Modelo de codificador de texto para codificar os prompts de entrada. vae ([`AutoencoderKLWan`, `AutoencoderDC` ou `AutoencoderKLLTX2Video`]) : Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos para e a partir de representações latentes. transformer ([SanaVideoTransformer3DModel](/docs/diffusers/v0.43.0/pt/api/models/sana_video_transformer3d#diffusers.SanaVideoTransformer3DModel)) : Transformer condicional para desruidar os latentes de entrada. scheduler ([DPMSolverMultistepScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/multistep_dpm_solver#diffusers.DPMSolverMultistepScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes de vídeo codificados. Pipeline para geração de texto para vídeo usando [Sana](https://huggingface.co/papers/2509.24695). Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.). #### __call__[[diffusers.SanaVideoPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 6.0, num_videos_per_prompt: int | None = 1, height: int = 480, width: int = 832, frames: int = 81, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, clean_caption: bool = False, use_resolution_binning: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 300, complex_human_instruction: list[str] = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for video generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, motion, and temporal relationships to create vivid and dynamic scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat slowly settling into a curled position, peacefully falling asleep on a warm sunny windowsill, with gentle sunlight filtering through surrounding pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps gradually lighting up, a diverse crowd of people in colorful clothing walking past, and a double-decker bus smoothly passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: ']) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video.py#L712) **Parâmetros:** prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração do vídeo. Se não definido, é necessário passar `prompt_embeds` em vez disso. negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração do vídeo. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`). num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, em detrimento de uma inferência mais lenta. timesteps (`list[int]`, *opcional*) : Passos de tempo personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumento `timesteps` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. Deve estar em ordem decrescente. sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. guidance_scale (`float`, *opcional*, padrão 4.5) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de vídeos que estão intimamente ligados ao `prompt` de texto, geralmente em detrimento de uma menor qualidade do vídeo. num_videos_per_prompt (`int`, *opcional*, padrão 1) : O número de vídeos a serem gerados por prompt. height (`int`, *opcional*, padrão 480) : A altura em pixels do vídeo gerado. width (`int`, *opcional*, padrão 832) : A largura em pixels do vídeo gerado. frames (`int`, *opcional*, padrão 81) : O número de quadros no vídeo gerado. eta (`float`, *opcional*, padrão 0.0) : Corresponde ao parâmetro eta (η) no paper DDIM: https://huggingface.co/papers/2010.02502. Aplica-se apenas a [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/ddim#diffusers.DDIMScheduler), será ignorado para os demais. generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística. latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o `generator` aleatório fornecido. prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`. prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção pré-gerada para embeddings de texto. negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativo pré-gerados. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`. negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção pré-gerada para embeddings de texto negativo. output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída do vídeo gerado. Escolha entre mp4 ou `np.array`. return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `SanaVideoPipelineOutput` em vez de uma tupla simples. attention_kwargs : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). clean_caption (`bool`, *opcional*, padrão `True`) : Se deve ou não limpar a legenda antes de criar os embeddings. Exige que `beautifulsoup4` e `ftfy` estejam instalados. Se as dependências não estiverem instaladas, os embeddings serão criados a partir do prompt bruto. use_resolution_binning (`bool` padrão é `True`) : Se definido como `True`, a altura e a largura solicitadas são primeiro mapeadas para as resoluções mais próximas usando `ASPECT_RATIO_480_BIN` ou `ASPECT_RATIO_720_BIN`. Após os latentes produzidos serem decodificados em vídeos, eles são redimensionados de volta para a resolução solicitada. Útil para gerar vídeos não quadrados. callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`. callback_on_step_end_tensor_inputs (`List`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline. max_sequence_length (`int` padrão é `300`) : Comprimento máximo da sequência a ser usado com o `prompt`. complex_human_instruction (`list[str]`, *opcional*) : Instruções para atenção humana complexa: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55. **Retorna:** [SanaVideoPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/sana_video#diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput) ou `tuple` Se `return_dict` for `True`, [SanaVideoPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/sana_video#diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput) é retornado; caso contrário, uma `tuple` é retornada, onde o primeiro elemento é uma lista com os vídeos gerados Função invocada ao chamar o pipeline para geração. Exemplos: ```py >>> import torch >>> from diffusers import SanaVideoPipeline >>> from diffusers.utils import export_to_video >>> pipe = SanaVideoPipeline.from_pretrained("Efficient-Large-Model/SANA-Video_2B_480p_diffusers") >>> pipe.transformer.to(torch.bfloat16) >>> pipe.text_encoder.to(torch.bfloat16) >>> pipe.vae.to(torch.float32) >>> pipe.to("cuda") >>> motion_score = 30 >>> prompt = "Evening, backlight, side lighting, soft light, high contrast, mid-shot, centered composition, clean solo shot, warm color. A young Caucasian man stands in a forest, golden light glimmers on his hair as sunlight filters through the leaves. He wears a light shirt, wind gently blowing his hair and collar, light dances across his face with his movements. The background is blurred, with dappled light and soft tree shadows in the distance. The camera focuses on his lifted gaze, clear and emotional." >>> negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience." >>> motion_prompt = f" motion score: {motion_score}." >>> prompt = prompt + motion_prompt >>> output = pipe( ... prompt=prompt, ... negative_prompt=negative_prompt, ... height=480, ... width=832, ... frames=81, ... guidance_scale=6, ... num_inference_steps=50, ... generator=torch.Generator(device="cuda").manual_seed(42), ... ).frames[0] >>> export_to_video(output, "sana-video-output.mp4", fps=16) ``` #### encode_prompt[[diffusers.SanaVideoPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_videos_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, clean_caption: bool = False, max_sequence_length: int = 300, complex_human_instruction: list[str] | None = None, lora_scale: float | None = None) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video.py#L303) **Parâmetros:** prompt (`str` ou `list[str]`, *opcional*) : prompt a ser codificado negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt negativo para orientar a geração do vídeo. Se não for definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`). Para o PixArt-Alpha, isso deve ser "". do_classifier_free_guidance (`bool`, *opcional*, padrão `True`) : se deve ou não usar classifier free guidance num_videos_per_prompt (`int`, *opcional*, padrão 1) : número de vídeos que devem ser gerados por prompt device : (`torch.device`, *opcional*): dispositivo torch onde os embeddings resultantes serão colocados prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`. negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embebidings de texto negativo pré-gerados. Para o Sana, deve ser os embebidings da string "". clean_caption (`bool`, padrão `False`) : Se `True`, a função pré-processará e limpará a legenda fornecida antes da codificação. max_sequence_length (`int`, padrão 300) : Comprimento máximo da sequência a ser usado para o prompt. complex_human_instruction (`list[str]`, padrão `complex_human_instruction`) : Se `complex_human_instruction` não estiver vazio, a função usará a instrução complexa do Humano para o prompt. Codifica o prompt em estados ocultos do codificador de texto. ## SanaImageToVideoPipeline[[diffusers.SanaImageToVideoPipeline]] #### diffusers.SanaImageToVideoPipeline[[diffusers.SanaImageToVideoPipeline]] ```python diffusers.SanaImageToVideoPipeline(tokenizer: GemmaTokenizer, text_encoder: Gemma2PreTrainedModel, vae: diffusers.models.autoencoders.autoencoder_dc.AutoencoderDC | diffusers.models.autoencoders.autoencoder_kl_ltx2.AutoencoderKLLTX2Video | diffusers.models.autoencoders.autoencoder_kl_wan.AutoencoderKLWan, transformer: SanaVideoTransformer3DModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video_i2v.py#L176) **Parâmetros:** tokenizer (`GemmaTokenizer` ou `GemmaTokenizerFast`) : O tokenizador usado para tokenizar o prompt. text_encoder (`Gemma2PreTrainedModel`) : Modelo de codificador de texto para codificar os prompts de entrada. vae ([`AutoencoderKLWan`, `AutoencoderDC` ou `AutoencoderKLLTX2Video`]) : Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos para e a partir de representações latentes. transformer ([SanaVideoTransformer3DModel](/docs/diffusers/v0.43.0/pt/api/models/sana_video_transformer3d#diffusers.SanaVideoTransformer3DModel)) : Transformer condicional para desruidar os latentes de entrada. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes de vídeo codificados. Pipeline para geração de vídeo a partir de imagem/texto usando [Sana](https://huggingface.co/papers/2509.24695). Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.). #### __call__[[diffusers.SanaImageToVideoPipeline.__call__]] ```python __call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 6.0, num_videos_per_prompt: int | None = 1, height: int = 480, width: int = 832, frames: int = 81, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, clean_caption: bool = False, use_resolution_binning: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 300, complex_human_instruction: list[str] = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for video generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, motion, and temporal relationships to create vivid and dynamic scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat slowly settling into a curled position, peacefully falling asleep on a warm sunny windowsill, with gentle sunlight filtering through surrounding pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps gradually lighting up, a diverse crowd of people in colorful clothing walking past, and a double-decker bus smoothly passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: ']) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video_i2v.py#L739) **Parâmetros:** image (`PipelineImageInput`) : A imagem de entrada para condicionar a geração do vídeo. O primeiro quadro do vídeo gerado será condicionado a esta imagem. prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração do vídeo. Se não definido, é necessário passar `prompt_embeds` em vez disso. negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração do vídeo. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`). num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, em detrimento de uma inferência mais lenta. timesteps (`list[int]`, *opcional*) : Passos de tempo personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumento `timesteps` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. Deve estar em ordem decrescente. sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. guidance_scale (`float`, *opcional*, padrão 4.5) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de vídeos que estão intimamente ligados ao `prompt` de texto, geralmente em detrimento de uma menor qualidade do vídeo. num_videos_per_prompt (`int`, *opcional*, padrão 1) : O número de vídeos a serem gerados por prompt. height (`int`, *opcional*, padrão 480) : A altura em pixels do vídeo gerado. width (`int`, *opcional*, padrão 832) : A largura em pixels do vídeo gerado. frames (`int`, *opcional*, padrão 81) : O número de quadros no vídeo gerado. eta (`float`, *opcional*, padrão 0.0) : Corresponde ao parâmetro eta (η) no paper DDIM: https://huggingface.co/papers/2010.02502. Aplica-se apenas a [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/ddim#diffusers.DDIMScheduler), será ignorado para os demais. generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística. latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o `generator` aleatório fornecido. prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`. prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção pré-gerada para embeddings de texto. negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativo pré-gerados. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`. negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção pré-gerada para embeddings de texto negativo. output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída do vídeo gerado. Escolha entre mp4 ou `np.array`. return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `SanaVideoPipelineOutput` em vez de uma tupla simples. attention_kwargs : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). clean_caption (`bool`, *opcional*, padrão `True`) : Se deve ou não limpar a legenda antes de criar os embeddings. Exige que `beautifulsoup4` e `ftfy` estejam instalados. Se as dependências não estiverem instaladas, os embeddings serão criados a partir do prompt bruto. use_resolution_binning (`bool` padrão é `True`) : Se definido como `True`, a altura e a largura solicitadas são primeiro mapeadas para as resoluções mais próximas usando `ASPECT_RATIO_480_BIN` ou `ASPECT_RATIO_720_BIN`. Após os latentes produzidos serem decodificados em vídeos, eles são redimensionados de volta para a resolução solicitada. Útil para gerar vídeos não quadrados. callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`. callback_on_step_end_tensor_inputs (`List`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline. max_sequence_length (`int` padrão é `300`) : Comprimento máximo da sequência a ser usado com o `prompt`. complex_human_instruction (`list[str]`, *opcional*) : Instruções para atenção humana complexa: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55. **Retorna:** [SanaVideoPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/sana_video#diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput) ou `tuple` Se `return_dict` for `True`, [SanaVideoPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/sana_video#diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput) é retornado; caso contrário, uma `tuple` é retornada, onde o primeiro elemento é uma lista com os vídeos gerados Função invocada ao chamar o pipeline para geração. Exemplos: ```py >>> import torch >>> from diffusers import SanaImageToVideoPipeline >>> from diffusers.utils import export_to_video, load_image >>> pipe = SanaImageToVideoPipeline.from_pretrained("Efficient-Large-Model/SANA-Video_2B_480p_diffusers") >>> pipe.transformer.to(torch.bfloat16) >>> pipe.text_encoder.to(torch.bfloat16) >>> pipe.vae.to(torch.float32) >>> pipe.to("cuda") >>> motion_score = 30 >>> prompt = "A woman stands against a stunning sunset backdrop, her long, wavy brown hair gently blowing in the breeze. She wears a sleeveless, light-colored blouse with a deep V-neckline, which accentuates her graceful posture. The warm hues of the setting sun cast a golden glow across her face and hair, creating a serene and ethereal atmosphere. The background features a blurred landscape with soft, rolling hills and scattered clouds, adding depth to the scene. The camera remains steady, capturing the tranquil moment from a medium close-up angle." >>> negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience." >>> motion_prompt = f" motion score: {motion_score}." >>> prompt = prompt + motion_prompt >>> image = load_image("https://raw.githubusercontent.com/NVlabs/Sana/refs/heads/main/asset/samples/i2v-1.png") >>> output = pipe( ... image=image, ... prompt=prompt, ... negative_prompt=negative_prompt, ... height=480, ... width=832, ... frames=81, ... guidance_scale=6, ... num_inference_steps=50, ... generator=torch.Generator(device="cuda").manual_seed(42), ... ).frames[0] >>> export_to_video(output, "sana-ti2v-output.mp4", fps=16) ``` #### encode_prompt[[diffusers.SanaImageToVideoPipeline.encode_prompt]] ```python encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_videos_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, clean_caption: bool = False, max_sequence_length: int = 300, complex_human_instruction: list[str] | None = None, lora_scale: float | None = None) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_sana_video_i2v.py#L301) **Parâmetros:** prompt (`str` ou `list[str]`, *opcional*) : prompt a ser codificado negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt negativo para orientar a geração do vídeo. Se não for definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`). Para o PixArt-Alpha, isso deve ser "". do_classifier_free_guidance (`bool`, *opcional*, padrão `True`) : se deve ou não usar classifier free guidance num_videos_per_prompt (`int`, *opcional*, padrão 1) : número de vídeos que devem ser gerados por prompt device : (`torch.device`, *opcional*): dispositivo torch onde os embeddings resultantes serão colocados prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`. negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embebidings de texto negativo pré-gerados. Para o Sana, deve ser os embebidings da string "". clean_caption (`bool`, padrão `False`) : Se `True`, a função pré-processará e limpará a legenda fornecida antes da codificação. max_sequence_length (`int`, padrão 300) : Comprimento máximo da sequência a ser usado para o prompt. complex_human_instruction (`list[str]`, padrão `complex_human_instruction`) : Se `complex_human_instruction` não estiver vazio, a função usará a instrução complexa do Humano para o prompt. Codifica o prompt em estados ocultos do codificador de texto. ## SanaVideoPipelineOutput[[diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput]] #### diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput[[diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput]] ```python diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput(frames: Tensor) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/sana_video/pipeline_output.py#L9) **Parâmetros:** frames (`torch.Tensor`, `np.ndarray` ou list[list[PIL.Image.Image]]) : Lista de saídas de vídeo - Pode ser uma lista aninhada de comprimento `batch_size,` em que cada sublista contém sequências de imagens PIL desruidas de comprimento `num_frames.` Também pode ser um array NumPy ou um tensor Torch de forma `(batch_size, num_frames, channels, height, width)`. Classe de saída para pipelines do Sana-Video.