Create a Video Generation Task

Create a video generation task with a multimodal content array. A successful request returns a task ID; use Query a task to poll the asynchronous result.

Request

Item	Value
Method	`POST`
URL	`https://api.tokenhub.belivestudios.com/v2/video_generation`
Authentication	`Authorization: Bearer sk-your-belive-studios-key`
Content-Type	`application/json`

curl https://api.tokenhub.belivestudios.com/v2/video_generation \
  -H "Authorization: Bearer sk-your-belive-studios-key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "An epic space opera trailer: a captain stands before a giant observation window as the final fleet jumps away."
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9",
  "aigc_watermark": false
}'

Request parameters

Field	Type	Required	Values / range	Description
`model`	string	Yes	`MiniMax-H3`, `MiniMax-H3-Max`	H3-Max does not support multimodal reference inputs or `2K`.
`content`	array	Yes	—	Multimodal input. Must include at least one non-empty `text` item; each text item is limited to 7,000 characters.
`resolution`	string	Yes	H3: `768P`/`2K`; H3-Max: `480P`/`768P`	Output resolution.
`duration`	integer	Yes	H3: 4–15; H3-Max: 5–15	Video duration in seconds.
`ratio`	string	Required for text-to-video	`adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`	Text-to-video cannot use `adaptive`; image-to-video follows the input image; reference generation defaults to `adaptive`.
`callback_url`	string	No	URL	Callback for status changes. The verification request must echo `challenge` within 3 seconds.
`aigc_watermark`	boolean	No	`true`/`false`	Whether to add an AIGC watermark; defaults to `false`.

`content` items

Each item has a type and the corresponding field:

`type`	Required field	`role`	Use
`text`	`text`	—	Prompt; required for every scenario.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, or `reference_image`	First/last-frame image-to-video or a reference image.
`video_url`	`video_url.url`	`reference_video`	Reference video; supported only by H3.
`audio_url`	`audio_url.url`	`reference_audio`	Reference audio; supported only by H3.

url accepts a public URL, mm_file://{file_id}, or a supported Base64 data URI. Image-to-video (first_frame/last_frame) and multimodal reference generation (reference_*) are mutually exclusive.

Common examples

First and last frame image-to-video

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "Push the camera from the street toward the character's face as they smile naturally."},
    {"type": "image_url", "image_url": {"url": "https://example.com/first.png"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://example.com/last.png"}, "role": "last_frame"}
  ],
  "resolution": "2K",
  "duration": 8,
  "ratio": "adaptive"
}

Multimodal reference generation (H3)

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "Follow the motion in the reference video and use the voice from the reference audio."},
    {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "https://example.com/motion.mp4"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"}
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

Media limits

The total request body must not exceed 64 MB. For large files, use a public URL or mm_file:// instead of embedding Base64.

Media	Limits
Image	JPG/JPEG/PNG/WEBP/HEIC/HEIF; ≤30 MB per file; 256–5760 px; aspect ratio 0.4–2.5; up to 1 first frame, 1 last frame, and 9 reference images.
Video	MP4/MOV; H.264/H.265 with AAC/MP3 audio; ≤50 MB per file; 2–15 seconds per clip, 15 seconds total; up to 3 clips; 23.976–60 fps. H3 reference video only.
Audio	WAV/MP3; ≤15 MB per file; 2–15 seconds per clip, 15 seconds total; up to 3 clips. H3 reference audio only.

Response

{
  "task_id": "task_01JZ3Q7M7Y7X5Y6R8K9P"
}

Field	Type	Description
`task_id`	string	Public BeLive Studio task ID for `GET /v2/query/video_generation/{task_id}`.

Asynchronous task

A successful create response means that the task was queued, not that the video is ready. Poll the query endpoint and read the video URL when the status becomes succeeded.

Common errors

HTTP status	Meaning	Common causes
`400`	Invalid parameters	Missing required fields, no non-empty text, or a duration/resolution outside the model limits.
`401`	Authentication failed	Missing or invalid `Authorization`.
`402`	Insufficient balance	Not enough account balance or video quota.
`422`	Content review failed	Prompt or media was flagged as sensitive.
`429`	Rate limited	Too many requests; retry later.
`500`	Server error	Upstream or gateway internal error.

Create a Video Generation Task

On this page