# Pika H3 Flex [Pika H3 Flex](https://huggingface.co/Pika-Labs/Pika-H3-Flex)는 [MiniMax-H3](./minimax_h3)를 6단계 비디오 및 오디오 생성기로 후학습한 Pika의 모델입니다. MiniMax-H3의 패킹 시퀀스, Qwen3-VL 컨디셔너, 두 개의 VAE를 그대로 유지하면서 두 가지를 변경했습니다. 먼저 샘플러로, Euler 업데이트 대신 각 단계마다 클린 예측을 재노이즈하는 고정 6단계 스케줄을 사용합니다. 두 번째로 가중치로, 두 개의 MiniMax-H3 트랜스포머 파티션 위에 적용되는 랭크 128 LoRA 어댑터 쌍을 사용합니다. 비디오와 이에 동기화된 스테레오 사운드는 동일한 6회의 포워드 패스에서 생성됩니다. 릴리스의 핵심은 어댑터입니다. FL2VA 어댑터(`fl2va/adapter.safetensors`)는 텍스트 및 엔드포인트 프레임 조건화를 위해 `transformer/` 파티션을 구동하고, Ref2VA 어댑터(`ref2va/adapter.safetensors`)는 멀티모달 참조를 위해 `transformer_ref/`를 구동합니다. 기본 구성 요소는 [MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)의 것으로 변경되지 않았으며, 저장소에는 독립적으로 로드될 수 있도록 해당 구성 요소의 사본이 포함되어 있습니다. Pika H3 Flex는 MiniMax-H3와 마찬가지로 [Modular Diffusers](../../modular_diffusers/overview) 블록으로만 통합됩니다. 즉, 해당 블록과 [PikaH3FlexModularPipeline](/docs/diffusers/main/ko/api/pipelines/pika_h3_flex#diffusers.PikaH3FlexModularPipeline)이 통합의 전부이며, `DiffusionPipeline` 부분은 존재하지 않습니다. ## 로딩 Pipeline은 두 단계로 조립됩니다. 먼저 `modular_model_index.json`을 통해 MiniMax-H3 기반 구성 요소와 두 개의 스케줄러 설정을 로드한 다음, 선택된 워크플로우의 어댑터를 [load_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.MiniMaxH3LoraLoaderMixin.load_lora_weights)로 위에 로드합니다. 어댑터는 diffusers 모듈 이름의 일반 PEFT 덤프이며, 학습된 스케일(`alpha == rank`, 1.0)로 로드됩니다. | 워크플로우 | 입력 | Transformer 파티션 | 어댑터 | |---|---|---|---| | `t2va` | `prompt` | `transformer/` | `fl2va/adapter.safetensors` | | `fl2va` | `prompt` 및 `image`와/또는 `last_image` | `transformer/` | `fl2va/adapter.safetensors` | | `ref2va` | `prompt` 및 `references` | `transformer_ref/` | `ref2va/adapter.safetensors` | ```py import torch from diffusers import ModularPipeline pipe = ModularPipeline.from_pretrained("Pika-Labs/Pika-H3-Flex", workflow="fl2va") pipe.load_components(dtype={"vae": torch.float32, "audio_vae": torch.float32, "default": torch.bfloat16}) pipe.load_lora_weights("Pika-Labs/Pika-H3-Flex", weight_name="fl2va/adapter.safetensors") ``` workflow를 전달하면 해당 작업에 맞게 블록이 정리되어, 해당 작업의 transformer 파티션만 가져오게 됩니다. 어댑터는 존재하는 파티션 하나로 라우팅되고, 파이프라인은 해당 작업의 요청만 처리합니다. `fl2va` 파이프라인은 keyframe이 필요하고, `t2va` 파이프라인은 keyframe을 받지 않습니다. 두 파티션을 모두 포함하는 파이프라인(`workflow=` 없이 로드된 경우)은 Ref2VA 어댑터의 위치를 지정해야 합니다: `pipe.load_lora_weights(..., weight_name="ref2va/adapter.safetensors", load_into_transformer_ref=True)`. 두 VAE는 공개된 패키지와 동일하게 float32로 배포되고 float32로 디코딩되며, 나머지 모든 연산은 bfloat16으로 수행됩니다. > [!TIP] > `pipe.doc`은 현재 파이프라인이 어떤 입력을 받아 어떤 출력을 반환하는지, 각 입력의 기본값, 기대하는 구성 요소, 생성하는 출력을 모두 보여 줍니다. ### 로드된 MiniMax-H3 재사용 기본 구성 요소는 MiniMax-H3의 것이므로, 이미 로드된 MiniMax-H3 파이프라인은 두 스케줄러와 어댑터를 제외한 모든 것을 보유하고 있습니다. 이 섹션에서는 로드된 구성 요소로부터 Pika H3 Flex 파이프라인을 조립하고, 두 파이프라인을 나란히 준비된 상태로 유지합니다. 하나의 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)가 각 구성 요소를 한 번만 보유하고 두 파이프라인 모두를 위해 오프로드하며, Pika H3 Flex 파이프라인은 두 스케줄러만 추가하고, 어댑터가 공유 트랜스포머가 두 모델 중 어느 것을 실행할지 결정합니다. ```py import torch from diffusers import ComponentsManager, ModularPipeline dtype = {"vae": torch.float32, "audio_vae": torch.float32, "default": torch.bfloat16} manager = ComponentsManager() manager.enable_auto_cpu_offload(device="cuda") # The MiniMax-H3 pipeline already in use, with every workflow loaded. `collection` registers its components in the # manager under that name, so they can be fetched by it later. minimax = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager, collection="minimax-h3") minimax.load_components(dtype=dtype) # The Pika H3 Flex pipeline, in its own collection. Only its own components are loaded: the two schedulers. pika = ModularPipeline.from_pretrained("Pika-Labs/Pika-H3-Flex", components_manager=manager, collection="pika-h3-flex") pika.load_components(names=["scheduler", "audio_scheduler"]) # The rest comes from the MiniMax-H3 collection, and `update_components` puts it in the Pika H3 Flex pipeline. shared = ["text_encoder", "tokenizer", "processor", "vae", "audio_vae", "transformer", "transformer_ref"] pika.update_components(**{name: manager.get_one(name=name, collection="minimax-h3") for name in shared}) # The adapters go into the shared transformers. pika.load_lora_weights("Pika-Labs/Pika-H3-Flex", weight_name="fl2va/adapter.safetensors") pika.load_lora_weights( "Pika-Labs/Pika-H3-Flex", weight_name="ref2va/adapter.safetensors", load_into_transformer_ref=True ) ``` `print(manager)`은 결과를 표시합니다. 모든 공유 구성 요소는 한 번씩 나열되며 두 컬렉션에 모두 속하고, Pika H3 Flex 컬렉션은 두 개의 스케줄러를 추가하며, 두 개의 transformers에는 어댑터가 있습니다. ```text Models: Name_ID | Class | Size (GB) | Collection transformer_1397... | MiniMaxH3Transformer3DModel | 63.02 | minimax-h3 | | | pika-h3-flex transformer_ref_13... | MiniMaxH3Transformer3DModel | 63.02 | minimax-h3 | | | pika-h3-flex text_encoder_1397... | Qwen3VLForConditionalGeneration | 62.13 | minimax-h3 | | | pika-h3-flex vae_1397... | AutoencoderKLMiniMaxH3 | 9.70 | minimax-h3 | | | pika-h3-flex audio_vae_1397... | AutoencoderKLMiniMaxH3Audio | 0.56 | minimax-h3 | | | pika-h3-flex Other Components: ID | Class | Collection scheduler_1397... | MiniMaxH3Scheduler | minimax-h3 audio_scheduler_1397... | MiniMaxH3Scheduler | minimax-h3 scheduler_1397... | MiniMaxH3Scheduler | pika-h3-flex audio_scheduler_1397... | MiniMaxH3Scheduler | pika-h3-flex tokenizer_1397... | Qwen2Tokenizer | minimax-h3 | | pika-h3-flex processor_1397... | Qwen3VLProcessor | minimax-h3 | | pika-h3-flex Additional Component Info: transformer_1397...: Adapters: ['default_0'] transformer_ref_13...: Adapters: ['default_0'] ``` 어댑터가 공유된 transformers가 어떤 모델인지 결정합니다. MiniMax-H3로 돌아가려면 `pika.disable_lora()`를 호출하면 됩니다. 그러면 다음 `minimax(...)` 요청은 베이스 모델로 실행됩니다. `pika.enable_lora()`는 Pika H3 Flex를 다시 활성화합니다. 이 사이에 아무것도 다시 로드되지 않으며, 각 파이프라인이 해당 구성 요소에 도달할 때마다 매니저가 해당 구성 요소를 가속기에서 켜거나 끕니다. ## MiniMax-H3와 다른 점 - **6단계, `num_inference_steps` 없음.** [MiniMaxH3Scheduler](/docs/diffusers/main/ko/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) 인스턴스 두 개(비디오는 `shift=12.0`, 오디오는 `shift=3.0`) 모두 파이프라인의 `denoising_step_list` 설정인 공개된 스케줄 `[1000, 750, 500, 250, 100, 40, 0]`에 대해 `stochastic_sampling`을 실행합니다. 각 단계에서 깨끗한 샘플을 예측하고, 마지막 단계를 제외한 모든 단계에서는 다음 시그마까지 새로운 노이즈로 다시 노이즈를 적용합니다. 단계 수는 어댑터의 계약 사항이며 입력 값이 아닙니다. - **각 단계마다 새로운 노이즈.** 요청은 `generator`에서 고정된 순서로 샘플링합니다: 조건부 노이즈를 위한 각 키프레임 또는 시각 참조에 대한 샘플링, 비디오 노이즈, 오디오 노이즈, 그리고 첫 5개 단계 각각의 비디오 및 오디오 재노이즈 샘플링입니다. `latents` 또는 `audio_latents`를 전달하면 초기 두 샘플링을 대체하고 나머지는 그대로 유지됩니다. - **Keyframe은 스트레칭이 아닌 크롭됩니다.** `fl2va` keyframe은 자체 해상도에서 캔버스의 종횡비로 중앙 크롭된 후 캔버스로 리사이즈됩니다. - **References는 캔버스의 해상도 티어를 따릅니다.** Pika H3 Flex는 버킷 테이블에서 생성을 수행합니다. 480p 티어와 768p 티어로 구성되며 각 티어당 11가지의 종횡비를 지원합니다. `ref2va` 요청은 해당 캔버스의 티어에 따라 조건이 설정됩니다. 이미지 참조는 768p 티어 미만에서는 1024픽셀의 짧은 변으로, 그 이상에서는 2048픽셀로 인코딩되며, 비디오 참조는 해당 티어 자체의 캔버스 규칙이 적용됩니다. 모든 비디오 또는 독립 오디오 참조는 2초에서 15초까지의 길이를 가지며, 비디오 길이와 독립 오디오 길이는 각각 최대 15초까지 합산될 수 있습니다. ## 생성 공개된 버킷은 Pika H3 Flex가 검증된 캔버스입니다. 하나를 `height`와 `width`로 전달하세요: | | 21:9 | 16:9 | 3:2 | 4:3 | 5:4 | 1:1 | 4:5 | 3:4 | 2:3 | 9:16 | 9:21 | |---|---|---|---|---|---|---|---|---|---|---|---| | 480p | 960x416 | 832x480 | 704x480 | 640x480 | 608x480 | 480x480 | 480x608 | 480x640 | 480x704 | 480x832 | 416x960 | | 768p | 1536x672 | 1344x768 | 1152x768 | 1024x768 | 960x768 | 768x768 | 768x960 | 768x1024 | 768x1152 | 768x1344 | 672x1536 | ```py import torch from diffusers import ComponentsManager, ModularPipeline from diffusers.utils import load_image from diffusers.utils.export_utils import encode_video # 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are # registered in a manager that moves each one on and off as the blocks reach it. manager = ComponentsManager() manager.enable_auto_cpu_offload(device="cuda") # or "mps", "xpu", "cpu" # Create one pipeline for all supported workflows, then load the `fl2va` workflow's components, which is # enough to run both the fl2va and t2va requests below. pipe = ModularPipeline.from_pretrained("Pika-Labs/Pika-H3-Flex", components_manager=manager) pipe.load_components( workflow="fl2va", dtype={"vae": torch.float32, "audio_vae": torch.float32, "default": torch.bfloat16} ) pipe.load_lora_weights("Pika-Labs/Pika-H3-Flex", weight_name="fl2va/adapter.safetensors") prompt = ( "integrated_multimodal_description: A cinematic close shot of a red ceramic cup on a wooden table beside an " "open window. A soft breeze moves a linen curtain. The camera slowly pushes toward the cup as warm morning " "light crosses the table.\n" "overall_soundscape: Gentle wind through the window and faint birdsong outside. No speech.\n" "non_diegetic_music: None.\n" ) outputs = ["videos", "audio", "sampling_rate"] # Text to video + audio on the 480p 16:9 bucket, 5 seconds. results = pipe( prompt=prompt, height=480, width=832, num_frames=124, generator=torch.Generator("cuda").manual_seed(42), output=outputs ) # First frame (and optionally `last_image`) to video + audio. The keyframe is center-cropped onto the canvas and # held as the first frame, so the prompt describes the keyframe and what happens from it. image = load_image( "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg" ) i2va_prompt = ( "For the target video, at 0.00 seconds into the target video, (from [Shot 1]) is fully referenced.\n\n" "integrated_multimodal_description: [Shot 1] Begin with the supplied image of a small toy astronaut figurine " "standing on a grey rocky moon surface, holding a white egg-shaped object. Preserve the figurine, its orange " "visor and the rocks. The astronaut slowly turns its helmet toward the camera and lifts the egg a little; fine " "dust drifts up around its boots. The camera slowly pushes in in one continuous shot. By the end the astronaut " "stands still, egg held up.\n\n" "overall_soundscape: Soft low wind and faint crunch of dust under the boots. No speech.\n\n" "non_diegetic_music: N/A\n" ) results = pipe( prompt=i2va_prompt, image=image, height=480, width=832, num_frames=124, generator=torch.Generator("cuda").manual_seed(42), output=outputs, ) encode_video( results["videos"][0], fps=24, output_path="pika_h3_flex_fl2va.mp4", audio=results["audio"][0], audio_sample_rate=results["sampling_rate"], ) ``` `ref2va` 워크플로우는 MiniMax-H3와 동일한 방식으로 정렬된 참조 목록을 받습니다. 최대 9개의 이미지, 3개의 비디오, 3개의 오디오 클립, 총 12개까지이며, 각 모달리티마다 하나의 참조 클래스를 사용합니다. 이 요청은 가장 많은 메모리가 필요합니다. 참조 항목은 시퀀스에 자체 행을 추가하며, 768p 해상도에서는 트랜스포머만으로도 80 GB 카드를 가득 채웁니다. 따라서 아래 예시에서는 트랜스포머의 블록을 CPU 메모리에서 하나씩 스트리밍하고, 매니저는 이전과 마찬가지로 다른 구성 요소를 디바이스로 올리고 내립니다. 이 예시는 80 GB 카드 하나에서 768p 참조 요청을 실행합니다. 스트리밍을 사용하지 않는 경우 480p로 제한해야 합니다. ```py import torch from diffusers import ComponentsManager, ModularPipeline from diffusers.modular_pipelines.pika_h3_flex import ( PikaH3FlexAudioReference, PikaH3FlexImageReference, PikaH3FlexVideoReference, ) manager = ComponentsManager() manager.enable_auto_cpu_offload(device="cuda") # or "mps", "xpu", "cpu" pipe = ModularPipeline.from_pretrained( "Pika-Labs/Pika-H3-Flex", workflow="ref2va", components_manager=manager ) pipe.load_components(dtype={"vae": torch.float32, "audio_vae": torch.float32, "default": torch.bfloat16}) pipe.load_lora_weights("Pika-Labs/Pika-H3-Flex", weight_name="ref2va/adapter.safetensors") # Keep the transformer in CPU memory and bring in one block at a time while it runs. pipe.transformer_ref.enable_group_offload( onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), offload_type="block_level", num_blocks_per_group=1, use_stream=True, ) results = pipe( prompt="subject_definitions: is the woman in . summary: [reference generation] waves at the camera.", references=[ PikaH3FlexImageReference.from_file("subject.png"), PikaH3FlexVideoReference.from_file("motion_ref.mp4"), # frames, their `fps` and the soundtrack PikaH3FlexAudioReference.from_file("voice.wav"), # waveform and its `sample_rate` ], height=768, width=1344, num_frames=124, generator=torch.Generator("cuda").manual_seed(42), output=["videos", "audio", "sampling_rate"], ) ``` ## PikaH3FlexModularPipeline[[diffusers.PikaH3FlexModularPipeline]] #### diffusers.PikaH3FlexModularPipeline[[diffusers.PikaH3FlexModularPipeline]] ```python diffusers.PikaH3FlexModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/modular_pipeline.py#L211) Pika H3 Flex, 즉 6단계로 후학습된 MiniMax-H3을 활용한 비디오 + 오디오 동시 생성을 위한 ModularPipeline입니다. `transformer/` 체크포인트 파티션에는 `fl2va` 어댑터와 함께 `t2va` (텍스트 전용) 및 `fl2va` (첫 번째 및/또는 마지막 키프레임) 워크플로우를, `transformer_ref/`에는 `ref2va` 어댑터와 함께 `ref2va` (오미-리퍼런스) 워크플로우를 사용합니다. 기본 구성 요소는 MiniMax-H3의 것이며, Pika H3 Flex 릴리스는 두 개의 transformer 파티션 위에 적용되는 rank-128 LoRA 어댑터 쌍입니다. 따라서 파이프라인은 두 단계로 조립됩니다. 구성 요소는 기본 구성 요소와 두 개의 스케줄러를 명시하는 `modular_model_index.json`을 통해 로드되고, 선택된 워크플로우의 어댑터는 [load_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.MiniMaxH3LoraLoaderMixin.load_lora_weights)로 로드됩니다. ```py import torch from diffusers import ModularPipeline pipe = ModularPipeline.from_pretrained("Pika-Labs/Pika-H3-Flex", workflow="fl2va") pipe.load_components(dtype={"vae": torch.float32, "audio_vae": torch.float32, "default": torch.bfloat16}) pipe.load_lora_weights("Pika-Labs/Pika-H3-Flex", weight_name="fl2va/adapter.safetensors") ``` MiniMax-H3와 마찬가지로, Pika H3 Flex는 텍스트 조건, 키프레임 또는 참조 조건 latent, 오디오 latent, 비디오 latent를 한 번에 포함하는 **하나의 패킹된 시퀀스**를 디노이즈합니다. 이 때문에 블록들은 모달리티별 텐서 대신 행 레이아웃을 전달하며, 파이프라인은 단일 transformer 호출 내에서 단계가 진행되는 두 개의 스케줄러(`shift = 12.0`는 비디오용, `shift = 3.0`는 오디오용)를 보유합니다. MiniMax-H3와 달리, 두 스케줄러는 고정된 6단계 `denoising_step_list`에 대해 `stochastic_sampling`를 사용하는 [MiniMaxH3Scheduler](/docs/diffusers/main/ko/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) 인스턴스입니다. `num_inference_steps`는 없으며, 모든 단계에서 요청의 generator에서 새로운 노이즈를 추출합니다. 어댑터는 기반 모델과 마찬가지로 가이던스 증류(distilled)되어 있습니다. 가이더, `negative_prompt`, `guidance_scale`이 없으며, 모든 단계에서 정확히 하나의 포워드 패스만 실행됩니다. 이 모듈은 각 블록이 참조하는 모델 정보를 담고 있습니다. config에서 파생된 기하학적 구조는 프로퍼티로, 캔버스, 티어 및 프레임 수 계산은 함수로 제공되며, 조건부 설정, 인코딩 및 노이즈 계약은 블록 자체에 정의되어 있습니다. ## PikaH3FlexBlocks[[diffusers.PikaH3FlexBlocks]] #### diffusers.PikaH3FlexBlocks[[diffusers.PikaH3FlexBlocks]] ```python diffusers.PikaH3FlexBlocks() ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/modular_blocks_pika_h3_flex.py#L668) Pika H3 Flex를 사용한 비디오 + 오디오 결합 생성을 위한 Auto Modular 파이프라인 블록: `references` 및 keyframe 입력에 따라 선택되는 `t2va` (텍스트 전용), `fl2va` (첫 번째 및/또는 마지막 keyframe), `ref2va` (omni-reference) 워크플로입니다. `t2va` 및 `fl2va` 워크플로는 `transformer` 파티션을 `fl2va` 어댑터와 함께 실행하고, `ref2va`는 `transformer_ref` 파티션을 `ref2va` 어댑터와 함께 실행하므로, 요청이 따르는 워크플로의 어댑터를 로드해야 합니다. `workflow=`가 없으면 구성 요소를 로드할 때 61.7GB의 **두 개의** transformer 파티션이 모두 로드되므로, 작업에 필요한 것만 로드하려면 하나를 전달하세요. 지원되는 워크플로: - `t2va`: `prompt` 필수 - `fl2va`: `prompt`, `image` 또는 `prompt`, `last_image`가 필요합니다 - `ref2va`: `prompt`, `references` 필수 구성 요소: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3`) audio_vae (`AutoencoderKLMiniMaxH3Audio`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer_ref (`MiniMaxH3Transformer3DModel`) transformer (`MiniMaxH3Transformer3DModel`) video_processor (`VideoProcessor`) 설정: canvas_short_edge (기본값: 768) canvas_max_pixels (기본값: 1032192) denoising_step_list (기본값: [1000, 750, 500, 250, 100, 40, 0]) Inputs: references (`list`, *선택 사항*): 조건으로 사용할 참조 자료입니다. **모델이 읽어야 할 순서대로** 제공해야 합니다. 순서는 프롬프트 제시 시 라벨을 지정하고 공유 회전 시계(rotary clock)에 배치하는 방식이므로, 순서가 다르면 다른 요청으로 처리됩니다. 각 모달리티당 하나의 dataclass를 사용하며, 모두 인메모리 미디어를 포함합니다. `PikaH3FlexImageReference`(최대 9개), 자체 `fps`를 가진 `PikaH3FlexVideoReference`(최대 3개, `audio` 사운드트랙도 조건으로 사용됨), 또는 자체 `sample_rate`를 가진 `PikaH3FlexAudioReference`(최대 3개)입니다. 참조 자료는 총 12개를 초과할 수 없으며, 오디오 참조 자료만 단독으로 사용할 수 없습니다. 모든 비디오 또는 단독 오디오 참조 자료는 2초에서 15초 사이여야 하며, 비디오 길이와 단독 오디오 길이는 각각 최대 15초를 초과할 수 없습니다. 이러한 블록은 미디어 파일을 열지 않습니다. 각 클래스의 `from_file` 클래스 메서드를 사용하여 디코딩하면 샘플링 속도가 함께 가져와집니다. height (`int`, *선택 사항*): 생성될 비디오의 픽셀 단위 높이로, 32의 배수여야 합니다. width (`int`, *선택 사항*): 생성될 비디오의 픽셀 단위 너비로, 32의 배수여야 합니다. num_frames (`int`, *선택 사항*): 고정된 24 fps에서 생성할 프레임 수입니다. 120에서 360 사이, 즉 5초에서 15초이며, 비디오 VAE가 디코딩할 수 있는 다음 `17 * n + 5` 값으로 올림됩니다. 참조 사운드트랙과 동일한 길이의 비디오를 생성하려면 `round(samples / sample_rate * 24)`를 전달하세요. image (`Image`, *선택 사항*): 비디오가 시작하는 키프레임입니다. 캔버스의 종횡비로 중앙 크롭된 후 캔버스에 리사이즈됩니다. 캔버스는 기본적으로 자체 종횡비에서 파생됩니다. last_image (`Image`, *선택 사항*): 비디오가 끝나는 키프레임입니다. 단독으로 전달하여 *최대* 프레임까지 생성할 수 있습니다. `image`와 마찬가지로 캔버스의 종횡비로 중앙 크롭된 후 캔버스에 리사이즈됩니다. prompt (`str`): 생성을 안내하는 프롬프트로, 단일 문자열입니다. normalized_references (`list`, *선택 사항*): 설정 단계에서 정규화된 참조 자료로, 패킹 순서대로 나열됩니다. keyframes (`list`, *선택 사항*): 대상 캔버스에 배치된 키프레임으로, 패킹 순서대로 나열됩니다. condition_latents (`list`, *선택 사항*): 인코딩된 비디오 조건 latents로, 패킹 순서대로 이미지 및 비디오 참조 자료마다 하나씩 있습니다. 이들의 shape은 모든 참조 자료 블록의 기하학적 구조를 결정합니다. audio_condition_latents (`list`, *선택 사항*): 인코딩된 오디오 조건 행(row)으로, 패킹 순서대로 오디오를 포함하는 참조 자료마다 하나씩 있습니다. generator (`Generator`, *선택 사항*): 요청의 generator입니다. 조건 노이즈는 생성될 행의 노이즈보다 먼저, 조건마다 한 번씩 이 generator에서 추출됩니다. latents (`Tensor`): `(1, 24, num_latent_frames, latent_height, latent_width)` shape의 사전 생성된 비디오 노이즈로, 추출 대신 사용됩니다. audio_latents (`Tensor`): `(2, 32, num_audio_latents)` shape의 사전 생성된 오디오 노이즈입니다. **denoiser_input_fields (`None`, *선택 사항*): transformer가 이름으로 읽는 패킹된 시퀀스의 구조적 설명입니다: `token_tags`, `position_ids` 및 세 개의 행 인덱스 텐서. attention_kwargs (`dict`, *선택 사항*): attention 프로세서용 추가 kwargs입니다. keyframe_anchors (`tuple`, *선택 사항*, 기본값 ()): 패킹 순서대로 각 키프레임이 비디오의 어느 끝에 앵커링되는지 지정합니다. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식입니다: 'pil', 'np' 또는 'pt'. Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): `(1, 2, num_samples)` 모양의 생성된 사운드트랙. sampling_rate (`int`): 생성된 사운드트랙의 Hz 단위 샘플링 레이트. ## PikaH3FlexImageReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexImageReference]] #### diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexImageReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexImageReference]] ```python diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexImageReference(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor]) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L83) **매개변수:** image (`PIL.Image.Image`, `np.ndarray` 또는 `torch.Tensor`) : 참조 이미지: 이미지, `(height, width, 3)` 배열 또는 `(3, height, width)` 텐서, `uint8` 또는 `[0, 1]` 범위의 부동소수점. 생성된 기하 구조에 절대 바인딩되지 않으며, 요청이 생성하는 캔버스와 무관하게 자체의 짧은 변(발행된 체크포인트의 경우 2048) 기준으로 인코딩됩니다. 주제, 스타일 또는 장면 참조: 요청당 최대 9개. #### from_file[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexImageReference.from_file]] ```python from_file(media) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L99) **매개변수:** media (`str` 또는 `os.PathLike`) : 이미지의 경로 또는 URL. `PikaH3FlexImageReference`에 [load_image()](/docs/diffusers/main/ko/api/utilities#diffusers.utils.load_image)를 통해 이미지 파일을 로드합니다. ## PikaH3FlexVideoReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexVideoReference]] #### diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexVideoReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexVideoReference]] ```python diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexVideoReference(frames: typing.Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor], fps: float | None = None, audio: typing.Optional[torch.Tensor] = None, sample_rate: int | None = None) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L111) **매개변수:** frames (`list[PIL.Image.Image]`, `np.ndarray` 또는 `torch.Tensor`) : 기준 프레임: 이미지 목록, `(num_frames, height, width, 3)` 배열 또는 `(num_frames, 3, height, width)` 텐서, `uint8` 또는 `[0, 1]` 범위의 부동 소수점. fps (`float`, *선택 사항*, 기본값 24.0) : `frames`가 가지는 프레임 레이트입니다. 이 값이 레퍼런스의 비전 블록을 컨디셔너의 2 fps 그리드에 배치하는 기준이 됩니다. MiniMax-H3 자체의 클록은 24 fps이므로, 다른 프레임 레이트의 경우 전체 프레임을 삭제하고 복제하여 24 fps로 리샘플링됩니다. 따라서 프레임이 파일에서 가져온 경우 이 필드를 올바르게 설정하는 것이 중요합니다. audio (`torch.Tensor`, shape `(channels, num_samples)`, *선택 사항*) : 이 비디오의 사운드트랙입니다. 모노 또는 스테레오 형식이며, 참조 대상의 고유한 사운드트랙으로 조건화됩니다. 생략하면 참조는 움직임만으로 조건화됩니다. sample_rate (`int`, *선택 사항*) : `audio`가 샘플을 처리하는 비율입니다. 이 값을 지정하지 않으면 오디오 VAE 자체의 비율을 사용하여 샘플이 그대로 유지되며, 다른 비율을 지정하면 해당 비율로 리샘플링됩니다. 모션 및 카메라 참조: 요청당 최대 3개까지 가능하며, 각 참조는 자체 사운드트랙과 함께 조건부로 사용됩니다. #### from_file[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexVideoReference.from_file]] ```python from_file(media) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L147) **매개변수:** media (`str` 또는 `os.PathLike`) : 비디오의 경로 또는 URL. **반환값:** `PikaH3FlexVideoReference` 컨테이너가 보고하는 프레임 레이트로 `(num_frames, height, width, 3)` `uint8` 프레임들을 반환하며, 오디오 스트림이 있는 경우 해당 사운드트랙과 그 사운드트랙의 샘플 레이트도 함께 포함합니다. `PikaH3FlexVideoReference`로 비디오 파일을 디코딩합니다. 이때 해당 비디오가 가진 해상도, 프레임 레이트, 사운드트랙을 그대로 유지합니다. 속도는 reference에 기록됩니다. [load_video()](/docs/diffusers/main/ko/api/utilities#diffusers.utils.load_video) 대신 이 방식으로 디코딩하는 이유가 바로 여기에 있습니다. MiniMax-H3는 reference를 자체 24 fps로 리샘플링하므로, 입력 과정에서 손실된 프레임 레이트는 잘못된 속도로 조건부 설정된 요청이 되며, 이를 알리는 어떠한 신호도 없습니다. 메타데이터가 잘못된 컨테이너의 경우, 반환된 reference에서 `fps` 또는 `sample_rate`를 오버라이드하여 수정할 수 있습니다. [PyAV](https://github.com/PyAV-Org/PyAV)가 필요합니다. ## PikaH3FlexAudioReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexAudioReference]] #### diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexAudioReference[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexAudioReference]] ```python diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexAudioReference(audio: Tensor, sample_rate: int | None = None) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L174) **매개변수:** audio (`torch.Tensor`, shape `(channels, num_samples)`) : 기준 웨이브폼, 모노 또는 스테레오. sample_rate (`int`, *선택 사항*) : `audio`가 샘플을 처리하는 비율입니다. 이 값을 지정하지 않으면 오디오 VAE 자체의 비율을 사용하여 샘플이 그대로 유지되며, 다른 비율을 지정하면 해당 비율로 리샘플링됩니다. 음성 또는 음악 참조: 요청당 최대 3개이며, 단독으로 사용할 수 없습니다. 오디오 참조는 최소 하나의 이미지 또는 비디오 참조와 함께 사용해야 합니다. conditioner에는 전달되지 않으며, 오디오 VAE에 의해만 인코딩됩니다. #### from_file[[diffusers.modular_pipelines.pika_h3_flex.PikaH3FlexAudioReference.from_file]] ```python from_file(media) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/pika_h3_flex/references.py#L193) **매개변수:** media (`str` 또는 `os.PathLike`) : 오디오의 경로 또는 URL, 또는 사운드트랙이 추출될 비디오의 경로 또는 URL. **반환값:** `PikaH3FlexAudioReference` 컨테이너가 보고하는 샘플 레이트의 `(channels, num_samples)` float32 웨이브폼 오디오 파일을 해당 파일이 포함하는 샘플 레이트로 `PikaH3FlexAudioReference`로 디코딩합니다. [PyAV](https://github.com/PyAV-Org/PyAV)가 필요합니다.