# MiniMax Hailuo-03 (H3) Reference to Video - Core.Today AI API

> MiniMax Hailuo-03 (H3) reference-to-video via Fal.AI. Generates video from multimodal references — subject/style images, motion video clips, and audio clips, each cited in the prompt by order — keeping subjects consistent while following the referenced motion and audio.

- **Provider**: MiniMax
- **Model ID**: minimax/h3/reference-to-video
- **Category**: Video Generation
- **Credits**: 1510 per 5s 2K video — billed per second (480P 116/s, 768P 140/s, 2K 302/s, 4K 372/s); up to 5 reference images
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Multimodal references: subject/style images, motion video clips, and audio clips in one request
- Cite references in the prompt by order — Image 1, Video 1, Audio 1
- Subject consistency across the generated take
- 5-15 second duration, adaptive or fixed aspect ratio (21:9 through 9:16)
- 480P/768P native generation, 2K/4K upscaled output

## Use Cases
- Character-consistent scenes driven by reference photos
- Motion transfer from a short reference clip to a new subject
- Lip-sync and audio-following takes from a reference audio clip
- Brand-consistent ad variations reusing the same subject references
- Style-matched sequels to an existing clip

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **prompt**: string - Text prompt for video generation. Refer to reference assets by their modality and order: Image 1, Image 2, Video 1, Audio 1, and so on

### Optional
- **reference_image_urls**: array - URLs of subject/style reference images, cited in the prompt as Image 1, Image 2, ... Up to 5 images
- **reference_video_urls**: array - URLs of motion/reference video clips (2-15s each, combined at most 15s), cited as Video 1, Video 2, ... Up to 3 clips
- **reference_audio_urls**: array - URLs of reference audio clips (2-15s each, combined at most 15s), cited as Audio 1, ... Up to 3 clips. Cannot be the only reference input
- **duration**: integer (default: 5) - The duration of the video in seconds (5-15). Billed per second
- **resolution**: string (default: 2K) - The resolution of the generated video. 480P and 768P are native generation modes; 2K and 4K upscale a 768P base result
  Options: 480P, 768P, 2K, 4K
- **aspect_ratio**: string (default: adaptive) - The aspect ratio of the generated video. 'adaptive' lets the model choose
  Options: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
- **prompt_expansion_mode**: string (default: balanced) - How much effort to spend rewriting the prompt before generation. 'fast' returns in about a second; 'quality' spends up to ~30s on a richer prompt
  Options: fast, balanced, quality
- **enable_safety_checker**: boolean (default: true) - If set to true, the safety checker will be enabled
- **seed**: integer - Random seed. A random seed is selected when omitted

## Examples

### Character-Consistent Scene
Keep a person and a pet consistent with their reference images
```json
{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "Image 1 is the female protagonist. Image 2 is her small dog. Keep the woman and dog consistent with their respective reference images while they walk together through a sunlit garden.",
    "reference_image_urls": [
      "https://example.com/person.jpg",
      "https://example.com/dog.jpg"
    ],
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "adaptive"
  }
}
```

### Motion Transfer
Follow the motion of a reference clip with a new subject
```json
{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "Image 1 is the dancer. Follow the motion of Video 1 while keeping the dancer consistent with Image 1.",
    "reference_image_urls": [
      "https://example.com/dancer.jpg"
    ],
    "reference_video_urls": [
      "https://example.com/dance-motion.mp4"
    ],
    "duration": 8,
    "resolution": "768P"
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- Cite every reference explicitly in the prompt (Image 1, Video 1, Audio 1) — uncited references contribute weakly
- Iterate at 480P or 768P, then re-render the final at 2K or 4K — the higher tiers upscale a 768P base
- Audio cannot be the only reference — pair it with at least one image or video
- Reference clips are capped at 15 seconds combined per modality; trim to the segment that matters
- Up to 5 reference images are supported per request on this gateway

## Documentation
https://fal.ai/models/minimax/h3/reference-to-video