HyperFlow API Guide

HyperFlow generates high-quality short videos from text, first/last frames, or omni-reference assets (image / video / audio). It is suited to content creation, film-style previews, and brand campaigns.

Three generation modes are supported (set by input.task):

• Text-to-video (t2v): generate a clip from a text description. This is the default when task is omitted.
• First/last frame (i2v): provide an opening and/or closing frame and generate a natural transition between them.
• Omni-reference (r2v): generate a video from reference images, videos, and audio.

Output is fixed at 24 FPS with native stereo. Resolutions available: 768p, 1088p.

Prompt enhancement is controlled by the top-level enhance_prompt field and is on by default.

Reference assets must be publicly reachable HTTP/HTTPS URLs. Base64 is not supported. task, aspect_ratio, resolution, and reference_inputs[].type are case-insensitive.

• Base URL: https://api-gen-na.bach.art/api/vdr
• Authentication: API Key (Bearer Token). Send Authorization: Bearer <API_KEY> in the request header.

About the model

This API is built on the open-weight base model MiniMax-H3. Video Rebirth's contribution is an inference-side few-step acceleration (HyperFlow, published at https://huggingface.co/videorebirth/hyperflow); the base weights, VAEs, conditioner, and the three official workflows remain the official implementations, and generation semantics are not rewritten.

Throughout this document, "the official specification" refers to the MiniMax-H3 documentation published by MiniMax:

• Model repository and technical notes: https://github.com/MiniMax-AI/MiniMax-H3
• Model weights and model card: https://huggingface.co/MiniMaxAI/MiniMax-H3

Consequently:

• Parameter semantics follow the official MiniMax-H3 specification. Except for the differences listed in the table below, the value ranges and asset constraints in this document are inherited from that specification. This API only wraps it at the protocol layer (authentication, queuing, callbacks, usage accounting) and does not reinterpret any parameter. Field names follow this API's own JSON conventions and map one-to-one onto the official ones.
• The table below lists every difference we are aware of in parameter semantics and capability scope. Operational limits (asset size, concurrency, queue depth and the like) are governed by the constraint tables in their own sections and are not recorded here. For other items not listed, this document describes the actual behaviour of this API. If you find a discrepancy that the table does not record, please report it — we will determine whether it is a documentation gap or an implementation defect, and either add it to the table or fix the implementation. The official specification may be updated independently; this API does not change automatically with it.
• Video Rebirth has no partnership, authorization, agency, or endorsement relationship with MiniMax. "MiniMax" and "MiniMax-H3" are trademarks of their respective owners and are named here only to identify the technical basis. This API is not a MiniMax product, nor a resale of any MiniMax official service.
• Use restrictions carry over from the base model. By calling this API you agree to the MiniMax H3 Community License Agreement and its Acceptable Use Policy. Under that agreement, this service is offered only within the Applicable Territory it permits. The MiniMax H3 model and the content it generates may not be used, reproduced, distributed or displayed outside that territory. Generated content posted publicly must be clearly disclosed as AI-generated, and outputs must not be used to train or improve other AI models.
• For the full licence text, see the LICENSE file shipped with the project: https://huggingface.co/MiniMaxAI/MiniMax-H3

Differences from the official specification

For the items below, this API's constraints differ from the official MiniMax-H3 specification. This table governs:

Create a task

Endpoint

• Protocol: HTTPS
• Path: /video/h3_hyperflow
• Method: POST
• Request format: application/json
• Response format: application/json

Submit a video generation request. Processing is asynchronous. On success the API returns a task_id; poll with GET /video/h3_hyperflow/{task_id}.

Request headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

• Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication, Bearer Token.

• Format: Bearer <API_KEY>
• Note: There is a space between Bearer and <API_KEY>.

Request body

enhance_prompt

Type: bool ｜ Required: No ｜ Default: true

Whether to enable prompt enhancement. When true: prompt enhancement is on. When false: prompt enhancement is off.

callback_url

Type: string ｜ Required: No ｜ Default: None

Callback URL for task-result notifications.

• Must be HTTP or HTTPS.
• Maximum 500 characters.
• If set, the server notifies this URL when the task status changes.

input

Type: object ｜ Required: Yes ｜ Default: None

Video generation parameters.

• See input properties below.

input properties

task

Type: string ｜ Required: No ｜ Default: t2v

Generation mode. Enum: t2v, i2v, r2v.

prompt

Type: string ｜ Required: Yes ｜ Default: None

Positive text prompt describing the video.

• Maximum 7,000 characters.
• Multilingual input is supported.
• For omni-reference (r2v), cite assets with @图片N / @视频N / @音频N in upload order within the same type. @ImageN / @VideoN / @AudioN are also accepted.

duration

Type: int ｜ Required: No ｜ Default: 5

Output duration in seconds (s). Range: 4 ~ 15.

generate_audio

Type: bool ｜ Required: No ｜ Default: true

Whether to include audio in the delivered video. When true: deliver with audio (native stereo). When false: deliver a silent track.

• Note: The model always generates audio; false only controls whether the final file keeps the audio track.

aspect_ratio

Type: string ｜ Required: No ｜ Default: See notes

Output aspect ratio (width:height). Enum: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, auto. Omitted, null, or an empty/whitespace-only string is treated as unspecified. If provided, it must be one of the enum values above; otherwise it is rejected.

• Text-to-video (t2v): must be one of the six fixed ratios; defaults to 16:9 when unspecified. auto is not supported.
• First/last frame (i2v): always auto, following the source image aspect ratio.
• Omni-reference (r2v): any of the six fixed ratios, or auto for the model to decide; defaults to auto when unspecified.

resolution

Type: string ｜ Required: No ｜ Default: 768p

Output resolution. Enum: 768p, 1088p.

• 768p: short side is 768 pixels when the aspect is between 16:9 and 9:16. Other aspects (for example 21:9) target about 1M pixels total, e.g. 21:9 is about 1536×672.
• 1088p: short side is 1088 pixels when the aspect is between 16:9 and 9:16.

image_url

Type: string ｜ Required: Conditionally ｜ Default: None

First-frame image URL; the starting reference for the generated video.

• Used only by i2v.
• Must be a publicly reachable HTTP/HTTPS URL.
• Image width and height in [256, 5760]; aspect ratio 5:2 ~ 2:5.
• Supported formats: JPG / JPEG / PNG / WEBP; each image ≤ 20MB.
• Note: If end_image_url is omitted, image_url is required.

end_image_url

Type: string ｜ Required: Conditionally ｜ Default: None

Last-frame image URL; the ending target for the generated video.

• Used only by i2v.
• Must be a publicly reachable HTTP/HTTPS URL.
• Same constraints as image_url.
• Note: If image_url is omitted, end_image_url is required. When both are set, the video interpolates naturally between the first and last frames.

reference_inputs

Type: array ｜ Required: Conditionally ｜ Default: None

Omni-reference assets.

• Used only by r2v.
• Item shape: reference_inputs items below.

Important: Omni-reference (r2v)

• reference_inputs must be non-empty
• Images ≤ 9; videos ≤ 3; audio clips ≤ 3
• Combined mix cap: 12 files
• Audio must be paired with an image or a video; audio-only is not allowed

Important: Prompt citations (r2v) Cite assets in same-type upload order, e.g. the first image is @图片1, the second video is @视频2. @Image1, @Video1, and @Audio1 are also accepted.

Reference video vs. reference image

A reference image supplies static information: character identity, object appearance, visual style, composition. A reference video additionally carries a time axis, so it can also serve as a motion, camera or pacing reference, or as a source video to be edited (see Video editing).

• When several assets are each given a distinct role (an image to fix the character, one video for motion, another for camera movement), the model tends to prioritise character identity and motion; secondary roles such as camera movement may be weakened or ignored. The fewer the roles, the more reliably each one is applied.

reference_inputs items

type

Type: string ｜ Required: Yes ｜ Default: None

Asset type.

Enum: image, video, audio.

url

Type: string ｜ Required: Yes ｜ Default: None

Asset URL.

• Must be a public HTTP/HTTPS URL.

start_time

Type: number ｜ Required: No ｜ Default: None

Start second for a reference video or audio clip. Must be ≥ 0. Used only for video / audio.

• Note. This parameter does not reduce the billed duration: a reference video is still billed for its full length.

Asset constraints (r2v)

Type	Count	Formats	Size	Other
Image	≤ 9	JPG / JPEG / PNG / WEBP	≤ 20MB each	Width and height [256, 5760]
Video	≤ 3	H.264/AVC, H.265/HEVC (in-track audio AAC / MP3); URL must end in .mp4 or .mov	≤ 50MB each	Duration [2, 15] s per clip, total ≤ 15 s; width and height [256, 5760]; aspect 5:2 ~ 2:5
Audio	≤ 3	WAV / MP3	≤ 15MB each	Must be paired with an image or video; duration [2, 15] s per clip, total ≤ 15 s

Billing basis (r2v)

• Reference images: the first 5 are free; billing starts from the 6th, per image
• Reference videos: billed separately by their own duration, rounded up to the second (5.2 s bills as 6 s); multiple clips are summed
• Reference audio: not billed
• Billed duration = output duration + the sum of all reference video durations

Request examples

Text-to-video (t2v)

curl --location --request POST 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "enhance_prompt": true,
    "input": {
      "task": "t2v",
      "prompt": "A cinematic daytime street scene.",
      "duration": 5,
      "generate_audio": true,
      "aspect_ratio": "16:9",
      "resolution": "768p"
    }
}'

First/last frame (i2v)

curl --location --request POST 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "enhance_prompt": true,
    "input": {
      "task": "i2v",
      "prompt": "Continue naturally between the endpoint frames.",
      "duration": 5,
      "generate_audio": true,
      "image_url": "https://example.com/first.png",
      "end_image_url": "https://example.com/last.png"
    }
}'

Omni-reference (r2v)

curl --location --request POST 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
      "task": "r2v",
      "prompt": "Lock the character with @Image1, use @Video1 as motion reference, and @Audio1 as voice reference.",
      "duration": 8,
      "aspect_ratio": "auto",
      "resolution": "768p",
      "reference_inputs": [
        { "type": "image", "url": "https://example.com/character.png" },
        { "type": "video", "url": "https://example.com/motion.mp4" },
        { "type": "audio", "url": "https://example.com/voice.wav" }
      ]
    }
}'

Video editing (r2v)

Video editing means making targeted changes to an existing video: replacing or adjusting the people, objects, scene, style or sound in it, while everything not mentioned is carried over from the source video.

This API does not define a separate generation mode for video editing — it is one way of using omni-reference (r2v). Pass the source video as a video item in reference_inputs, cite it in the prompt with @视频N (or @VideoN), and state clearly what to change and what to keep.

This matches the official MiniMax-H3 specification: official likewise defines no separate video-editing mode; the source video enters the full-reference (Ref2VA) workflow as a reference video, and "video editing" is a task type defined by the official prompt guide, expressed through the prompt. This section therefore introduces no new parameters or constraints.

Important: Video editing (r2v)

• No separate endpoint, task value or dedicated field; task remains r2v
• The source video is a video item in reference_inputs; count, format, size and duration constraints are identical to any other r2v asset
• Whether the result is an "edit" or a "reference" is decided by the prompt
• Query method, response shape, task states and usage accounting are identical to any other r2v task

Video editing vs. video reference

Passing a video into r2v can mean two different things. Make the intent explicit in the prompt:

• Note. A prompt that says only "follow the motion of @视频1" expresses a video reference, not video editing.
• Note. When several assets are each given a distinct role (an image to fix the character, one video for motion, another for camera movement), the model tends to prioritise character identity and motion; secondary roles such as camera movement may be weakened or ignored. The fewer the roles, the more reliably each one is applied.

Parameters in a video-editing request

Field definitions, ranges and constraints are given in input properties and reference_inputs items above; this section only covers their use when editing.

• Note. duration does not follow the source automatically; when omitted it still defaults to 5. The official specification does not define the behaviour when output and source durations differ, so temporal correspondence with the source cannot be guaranteed in that case.
• Note. duration has a minimum of 4. A source shorter than 4 seconds cannot be matched exactly; use sources of at least 4 seconds.
• Note. Fixing an aspect_ratio that differs from the source forces the frame to be recomposed, which makes "keep everything else unchanged" hard to achieve.
• Note. Output specs follow this API (24 FPS, the resolution given by resolution), not the source's frame rate or resolution.

Writing the prompt for video editing

With prompt enhancement on (enhance_prompt: true, the default), plain natural language is enough — you do not need to know the official structured prompt format. Recommended practice:

• Note. For editing tasks, prompt enhancement time rises sharply with the source video's length and complexity and can exceed the video generation time itself. Allow headroom in your timeouts and user-facing progress messaging.

1. Cite the source and use an editing verb. Open with "Edit @视频1: …" or "Modify the … in @视频1" so it is unambiguous that the source is being changed.
2. State what changes. Be specific about object, position and target state, e.g. "change the grey suit on the man at the left to a dark blue denim jacket"; avoid vague phrasing like "change the style".
3. State what is preserved. Spell out character identity, motion, camera movement, composition, background, lighting and pacing, or close with "keep everything else unchanged".
4. Explain the role of any new asset. When passing images or audio, say what they are for, e.g. "replace with the person in @图片1", "voice timbre reference @音频1".
5. Address the sound. If the source's original audio (dialogue, music, ambience) should be retained, say so explicitly. To reuse a specific track verbatim, pass it as a separate audio item and note "reuse @音频1 as is". When adding or changing dialogue, give the exact lines.

• Note. With generate_audio: false the result is delivered with a silent track regardless of what the prompt says about preserving the original sound.

Common edit types and prompt examples

Edit effectiveness depends strongly on the scope of the change. Instructions aimed at a specific element in the frame are the most reliable. Instructions requiring a sustained change across the whole frame or the whole audio track (overall style, overall lighting, camera movement, background music) tend to be ignored in favour of staying faithful to the source. Choose your approach accordingly.

Changes aimed at a specific element (reliable)

Changes spanning the whole frame or the whole audio track (unreliable, not recommended)

• If any of these three is a hard requirement, use another route: overall grading and scoring are better done in an editor after delivery, and stylised content is better generated from scratch with text-to-video (t2v) than converted from an existing video.
• The tables above are common examples, not an exhaustive capability list; results also depend on the complexity of the source and the precision of the instruction.

Video-editing request examples

Attribute change (single source video). The example assumes a 6-second source.

curl --location --request POST 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
      "task": "r2v",
      "prompt": "Edit @视频1: change the woman'"'"'s beige trench coat to a red leather jacket. Keep her identity, motion, the camera movement, background, lighting and the original audio unchanged.",
      "duration": 6,
      "aspect_ratio": "auto",
      "resolution": "768p",
      "reference_inputs": [
        { "type": "video", "url": "https://example.com/source.mp4" }
      ]
    }
}'

Making a person speak, with a voice-timbre reference (video + audio). The example assumes a 5-second source.

curl --location --request POST 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
      "task": "r2v",
      "prompt": "Edit @视频1: have the person speak to camera: \"Welcome to today'"'"'s show.\" Lip-sync to the line, voice timbre referencing @音频1. Keep the rest of the picture unchanged.",
      "duration": 5,
      "aspect_ratio": "auto",
      "resolution": "768p",
      "reference_inputs": [
        { "type": "video", "url": "https://example.com/source.mp4" },
        { "type": "audio", "url": "https://example.com/voice.wav" }
      ]
    }
}'

With prompt enhancement turned off

Keeping enhance_prompt on is recommended for video editing: the official structured prompt requires a complete shot-by-shot description of the source, which is costly and error-prone to write by hand.

If you must turn it off (enhance_prompt: false), the prompt is passed through unchanged and the result depends on whether it follows the official "full-reference mode" structure — six sections (subject_definitions / summary / retention_analysis / detailed_description / overall_soundscape / non_diegetic_music), with the source video declared on its own line under subject_definitions, summary opening with [video editing], and retention_analysis stating the retention relationship for each label. Follow the official prompt guide for the complete rules: https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md. This API does not alter its semantics.

• The official label <Video N> corresponds to this API's @视频N: both mean the Nth video in upload order.

Video-editing caveats

• The source must satisfy the r2v video asset constraints above ([2, 15] s per clip, and see the video-format row in Differences from the official specification). Trim clips longer than 15 seconds yourself.
• "Keep unchanged" is semantic and perceptual, not pixel-exact. Editing regenerates the entire clip; untouched regions are reconstructed by the model as well.
• Avoid too many edits in one request. For several changes, iterate: submit the video_url returned by the previous task as the new source (make sure the URL is still publicly reachable at submission time and satisfies the asset constraints). Each round regenerates the whole clip, so too many rounds can accumulate quality loss.
• The larger the change, the closer it gets to plain generation. Substantially altering the subject's motion, the camera or the duration reduces consistency with the source; such needs are better expressed as a video reference.

Response body

{
  "code": 200,                                            // Status code; 200 on success, not 200 on failure (see message)
  "message": "Success",                                   // Result description
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",    // Task ID, used to query the result
    "status": "TASK_PENDING",                             // Task status; see "Task status enum"
    "created_at": 1778313600                              // Creation time, Unix timestamp in seconds (s)
  },
  "timestamp": 1778313600                                 // Response time, Unix timestamp in seconds (s)
}

code

Type: int

Status code. 200 on success; not 200 on failure (see message).

message

Type: string

Result description.

task_id

Type: string

Task ID, used to query the result.

status

Type: string

Task status. See Task status enum.

created_at

Type: number

Task creation time, Unix timestamp in seconds.

timestamp

Type: number

Response time, Unix timestamp in seconds.

Query a task (single)

Endpoint

• Protocol: HTTPS
• Path: /video/h3_hyperflow/{task_id}
• Method: GET
• Request format: application/json
• Response format: application/json

Query progress and result for a given task. On success, the response includes a video download URL.

Request headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

• Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication, Bearer Token.

• Format: Bearer <API_KEY>
• Note: There is a space between Bearer and <API_KEY>.

Path parameters

task_id

Type: string ｜ Required: Yes ｜ Default: None

Task ID returned when the task was created.

• Note: Path parameter; put the value in the request path.

Request example

curl --location --request GET 'https://api-gen-na.bach.art/api/vdr/video/h3_hyperflow/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response body

{
  "code": 200,                                            // Status code; 200 on success
  "message": "Success",                                   // Result description
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",    // Task ID
    "status": "TASK_SUCCEEDED",                           // Task status; see "Task status enum"
    "created_at": 1778313600,                             // Creation time, Unix timestamp in seconds
    "started_at": 1778313610,                             // Processing start time, Unix timestamp in seconds
    "completed_at": 1778313700,                           // Completion time, Unix timestamp in seconds
    "video_url": "https://example.com/result.mp4",        // Download URL; returned only when TASK_SUCCEEDED
    "usage": {                                            // Usage; returned only in a terminal state
      "video_output": 5                                   // Video duration in seconds; equals create-time duration on success, 0 on failure
    }
  },
  "timestamp": 1778313700                                 // Response time, Unix timestamp in seconds
}

task_id

Type: string

Task ID.

status

Type: string

Task status. See Task status enum.

created_at

Type: number

Task creation time, Unix timestamp in seconds.

started_at

Type: number

Processing start time, Unix timestamp in seconds.

completed_at

Type: number

Completion time, Unix timestamp in seconds.

video_url

Type: string

Generated video download URL.

• Note: Returned only when TASK_SUCCEEDED.

usage

Type: object

Usage.

• Returned only in a terminal state.
• video_output is the video duration in seconds; on success it equals the duration used at create time, on failure it is 0.

Task status enum

• TASK_PENDING: submitted, waiting to run
• TASK_PROCESSING: in progress
• TASK_SUCCEEDED: video generated successfully
• TASK_FAILED: video generation failed

Appendix: Authentication and token generation

Every API request must include Authorization in the header.

Authorization: Bearer <API_TOKEN>

API_TOKEN is generated from AccessKey and SecretKey. The JWT is signed with HS256 and follows RFC 7519.

Generate a token

The following Python example shows how to mint an industry-standard JWT Bearer Token.

# Python example: generate a JWT Bearer Token
import jwt
from datetime import datetime, timedelta

ak = ""  # AccessKey
sk = ""  # SecretKey

def generate_token(ak: str, sk: str) -> str:
    now = datetime.now()

    headers = {
        "alg": "HS256",
        "typ": "JWT",
    }

    payload = {
        "iss": ak,
        "nbf": int((now - timedelta(seconds=5)).timestamp()),
        "exp": int((now + timedelta(days=10)).timestamp()),
    }

    return jwt.encode(payload, sk.encode("utf-8"), headers=headers)

api_token = generate_token(ak, sk)
print(api_token)

Security notes

• Do not expose SecretKey in a browser, mobile app, or public repository.
• Generate the token on your server, then call the Bach API from the server.
• If authentication fails, first check that the token is not expired, the signature is correct, and there is a space between Bearer and the token.

• Version: v1.2
• Last updated: 2026-09-21
• © 2026 Video Rebirth team. All rights reserved.
• Powered by MiniMax H3. Not a MiniMax product; no affiliation, partnership, or endorsement. See About the model.