GEgenaipro
H3 Video

H3 Reference to Video

Changed on

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

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.

post/v2/hailuo/reference-to-video

Request

Request body multipart/form-data

reference_videostring binary required

Reference video — MP4, max 50 MB and 15 s, 256–6000 px on each side, aspect ratio 2:5–5:2

reference_imagestring binary

Optional reference image — JPEG/PNG/WebP, max 20 MB, short side ≥ 300 px, long side ≤ 5760 px, aspect ratio 2:5–5:2

promptstring 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_videosstring

Number of videos to generate (1–4). Sent as string in form data.

durationstring

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_urlstring

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.

Example request

{
  "prompt": "The character performs the same dance on a rooftop",
  "aspect_ratio": "9:16",
  "callback_url": "https://your-server.example.com/genaipro-webhook"
}

Response

Task accepted for processing

idstring

Task ID (use for GET /v2/hailuo/tasks/{id})

promptstring

The prompt used for generation (for Boost HD, the source task's prompt)

file_urlsstring[]

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

errorstring

Error message — present only when status is failed

task_typestring

text_to_video, frames_to_video, reference_to_video or upscale_video (image tasks: create_image)

aspect_ratiostring

Aspect ratio of the task — Auto for frames-to-video (follows the start image)

modelstring

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_outputsinteger

Number of videos (or images) requested

created_atstring date-time

Timestamp when the task was created

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prompt": "A drone flying over mountains at sunrise",
  "file_urls": [],
  "task_type": "text_to_video",
  "aspect_ratio": "16:9",
  "model": "h3_768p_10s",
  "number_of_outputs": 1
}

Changes