---
title: "H3 Reference to Video"
method: POST
path: "/v2/hailuo/reference-to-video"
tags: ["H3 Video"]
---

# H3 Reference to Video

`POST /v2/hailuo/reference-to-video`

## Request

- Base URL: `https://genaipro.io/api`
- URL: `https://genaipro.io/api/v2/hailuo/reference-to-video`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/genaipro/apis/genaipro-api/docs/v2/hailuo/reference-to-video/post.ts> (a function with typed inputs; its response is checked against the schema)

Generate an **H3** video guided by a reference video (required) and an optional reference image. Returns immediately with `202 Accepted`. H3 Max is not supported in this mode.

Price per video depends on total seconds (`duration` + reference-video length) — see the reference-to-video table under *Credits* in the **H3 Video** tag. Example below: 768p, 5 s output + 6 s reference = 11 s → 2 credits.

### Example

```bash
curl -X POST https://genaipro.io/api/v2/hailuo/reference-to-video \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "reference_video=@motion.mp4" \
  -F "reference_image=@character.png" \
  -F "prompt=The character performs the same dance on a rooftop" \
  -F "aspect_ratio=9:16" \
  -F "duration=5"
```

> **Rate limit:** 30 requests/minute — shared across all `/v2/hailuo` creation endpoints.

## Request body `multipart/form-data`

- object
  - `reference_video` string, binary, required: Reference video — MP4, max 50 MB and 15 s, 256–6000 px on each side, aspect ratio 2:5–5:2
  - `reference_image` string, binary: Optional reference image — JPEG/PNG/WebP, max 20 MB, short side ≥ 300 px, long side ≤ 5760 px, aspect ratio 2:5–5:2
  - `prompt` string, required: Text description of the video (at most 2400 characters)
  - `model` 'h3': Only `h3` is supported
  - `aspect_ratio` '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Video aspect ratio
  - `number_of_videos` string: Number of videos to generate (1–4). Sent as string in form data.
  - `duration` string: Output length in whole seconds — 5–15 (`2k`: 5–12). `duration` + reference-video length must stay within the reference-to-video price table (768p ≤ 21 s, 2k ≤ 12 s), otherwise `400`. Sent as string in form data.
  - `resolution` '768p' | '2k': Output resolution
  - `callback_url` string: Optional `http`/`https` webhook URL. When the task reaches `completed` or `failed`, GenAIPro POSTs the task object (same shape as `GET /v2/hailuo/tasks/{id}`) to this URL.

## Response `202`

Task accepted for processing

- H3Task: Task object returned by every `/v2/hailuo` endpoint — creation (`202`), `GET /tasks/{id}`, `GET /histories`, the `hailuo_task_updated` WebSocket event and the `callback_url` webhook.
  - `id` string: Task ID (use for `GET /v2/hailuo/tasks/{id}`)
  - `prompt` string: The prompt used for generation (for Boost HD, the source task's prompt)
  - `file_urls` string[]: URLs of the generated files (empty while processing). Public; deleted about 90 days after creation (then `404`) — download them yourself.
  - `status` 'processing' | 'completed' | 'failed': Task status
  - `error` string: Error message — present only when `status` is `failed`
  - `failed_slots` object[]: Outputs that failed while the rest completed (their credits are refunded). Present only when `status` is `completed` and some outputs failed; `file_urls` contains only the generated files.
    - `index` integer: 0-based position of the failed output in the request
    - `error` string
  - `task_type` string: `text_to_video`, `frames_to_video`, `reference_to_video` or `upscale_video` (image tasks: `create_image`)
  - `aspect_ratio` string: Aspect ratio of the task — `Auto` for frames-to-video (follows the start image)
  - `model` string: Model and options of the task. Video: `<model>_<resolution>_<duration>s` (e.g. `h3_768p_10s`, `h3_max_480p_5s`); Boost HD: `upscale_<resolution>` (e.g. `upscale_1440p`).
  - `number_of_outputs` integer: Number of videos (or images) requested
  - `created_at` string, date-time: Timestamp when the task was created

## Other responses

- `400`: Invalid request (missing `reference_video`, video or image outside the limits, model other than `h3`, combination over the per-video limit, insufficient credits)
- `401`: Missing or invalid API token
- `403`: H3 video generation is not enabled for your account, or video generation is temporarily disabled
- `413`: Request body exceeds 71 MB
- `429`: Rate limit exceeded
- `503`: No capacity for this model right now (nothing is charged) — retry later

## Changes

- **2026-10-29** `8e065c159192`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/genaipro/apis/genaipro-api/changes/v2/hailuo/reference-to-video/post.md)

---

[API](https://skmtc.dev/genaipro/apis/genaipro-api.md) - [All operations](https://skmtc.dev/genaipro/apis/genaipro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/genaipro/apis/genaipro-api/revisions/264ca07ba262?raw)