MiniMax H3 Text-to-Video API

minimax/h3/text-to-video

2K · 5–15 sec

MiniMax H3 Text-to-Video turns a prompt into a fixed 2K video. Describe the subject, action, camera movement, lighting, and visual style, then choose a duration from 5 to 15 seconds and an aspect ratio.

Input

Prompt

460/2000

Resolution

Duration

Aspect ratio

Output

Ready

Continue with

MiniMax H3 Image-to-Video MiniMax H3 Reference-to-Video

REST API

Quick Start

Make your first request in three steps. Start with the short example, confirm that it returns a task_id, then retrieve the generated video.

Connect to the Vidgo API

Create an API key, keep it on your server, and send it in the Authorization header as a Bearer token.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

Choose a language and run the short example. A successful submission returns a task_id; it does not wait for the video to finish.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "minimax/h3/text-to-video",
  "input": {
    "prompt": "A cyclist races through a rain-lit city as the camera tracks beside her.",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}'

Wait for the result

Use the returned task_id to check the same task until it reaches finished or failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll about every 2 seconds while the status is not_started or running. Stop on finished or failed; on success, read data.files[].file_url. For long-running jobs, increase the interval gradually, or add callback_url to the submit request to receive the final result asynchronously.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete runnable example

Open this after the three-step flow is clear. It combines submission, polling, terminal-state handling, and result extraction in one script.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "minimax/h3/text-to-video",
  "input": {
    "prompt": "A cyclist races through a rain-lit city as the camera tracks beside her.",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

Send model and optional callback_url at the top level. Put all generation parameters inside input. Unsupported media fields are rejected; do not send fields that are not listed below.

Field	Type	Required	Default	Description
model	string	Yes	—	Must be minimax/h3/text-to-video.
callback_url	string (URL)	No	—	Optional public HTTP(S) endpoint that receives the final asynchronous result. Omit it when polling.
input	object	Yes	—	Container for the model-specific generation parameters below.
input.prompt	string	Yes	—	Trimmed text prompt from 1 to 2,000 characters. Source-media fields are not accepted.
input.duration	integer	No	5	Generated duration in whole seconds, from 5 through 15.
input.resolution	string	No	2K	Fixed output resolution. The only accepted value is 2K.
input.aspect_ratio	string	No	—	One of 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. adaptive is not accepted.

Response Fields

Submission returns the task identity immediately. Status responses add progress, output files, or a failure message as the task advances.

Field	Type	Description
code	integer	Application result code. Successful responses use 0 or 200.
message	string	Human-readable response or error message when present.
data.task_id	string	Task identifier used in the status endpoint path.
data.status	string	Current state: not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	number	Completion percentage when the provider reports progress.
data.files[]	array	Generated output files returned after a successful task.
data.files[].file_url	string	Public URL of the generated video.
data.files[].file_type	string	Generated file type, such as video.
data.files[].watermark_url	string \| null	Watermarked output URL when one is available.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read the video URL from data.files[].file_url.
failed
Generation stopped with an error. Read data.error_message and do not continue polling.

Polling and Errors

AuthenticationA 401 response indicates a missing or invalid Bearer API key. Correct the credential before retrying.
ValidationA 400 response means the request is invalid. Read the response message and correct the named field.
Polling intervalStart around every 2 seconds. Increase the interval gradually for long-running tasks.
Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url to receive the final asynchronous result; otherwise use the status endpoint.

Model Specifications

Specification	Value	Details
Input mode	Text only	A prompt defines the complete scene; source media is not accepted.
Output	Video	MiniMax H3 Text-to-Video API returns an asynchronous video generation task.
Resolution	2K	Resolution is fixed and does not change the credit rate.
Duration	5–15 seconds	Use a whole-second value; the default is 5 seconds.
Aspect ratio	6 fixed ratios	Supports 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16; adaptive is not accepted.
Billing basis	21 credits / second	Only generated duration contributes to the request cost.

View MiniMax H3 Text-to-Video API documentation

MiniMax H3 Text-to-Video API

MiniMax H3 Text-to-Video API accepts a 1–2,000-character prompt and returns an asynchronous fixed-2K video task. Set a whole-second duration from 5 to 15 and choose one of six fixed aspect ratios; source-media fields are rejected.

Why Choose MiniMax H3 Text-to-Video API?

Direct prompt-to-video workflow.Create a complete scene from natural language when no source asset exists.
Scene and camera control.Direct the subject, action, shot, camera movement, lighting, and mood in one prompt.
Six selectable aspect ratios.Choose 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16 for the generated video.
Selectable clip length.Choose any whole-second duration from 5 through 15 to match the action.
Fixed 2K resolution and per-second pricing.Every supported duration and aspect ratio uses fixed 2K output at 21 credits per generated second.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the subject, setting, action, camera, and visual direction in 1 to 2,000 characters after trimming.
duration	Optional	Whole seconds from 5 through 15. Default`55–15`
resolution	Fixed	No other resolution is accepted. Default`2K`
aspect_ratio	Optional	Choose one fixed ratio. Adaptive is not supported. `21:916:94:31:13:49:16`

How to Use

Define the sceneName the subject and setting, then identify the main action that should appear in the video.
Write one main actionUse concrete verbs and keep a short clip focused on one readable event.
Direct the shotAdd shot size, camera movement, pace, lighting, and mood.
Set format and timingChoose one fixed aspect ratio and a whole-second duration from 5 through 15.
Submit and trackRun the request, then poll the returned task ID or use a callback URL.

Pricing

Pricing depends only on generated duration: 21 credits for each second of output. Fixed 2K resolution does not change the rate.

Usage	Rate	Details
Generated video	21 credits per second	A 5 second clip costs 105 credits, a 10 second clip costs 210 credits, and a 15 second clip costs 315 credits.

Best Use Cases

Campaign ConceptsTurn a creative brief into short motion concepts for review and variant testing.
Social VideoCreate landscape, square, portrait, and vertical clips from one prompt-led workflow.
Game and Film PrevisualizationExplore staging, camera language, atmosphere, and action before committing to production.
Motion and Atmosphere StudiesTest a single action, camera move, lighting setup, or visual mood before production.

Pro Tips

Write in this order: subject and setting, main action, camera direction, then lighting and mood.
Use concrete motion verbs and describe subject movement separately from camera movement.
Keep short clips focused on one action beat instead of a chain of unrelated events.
Describe how the action develops over time when pacing or a final beat matters.
Choose the delivery ratio before describing framing so the composition matches the final placement.
Remove instructions that compete with the main subject, camera direction, or intended visual style.

Notes

MiniMax H3 Text-to-Video API rejects source-image, source-video, and source-audio fields.
A successful submission returns a task ID rather than a completed video.
Poll while status is not_started or running; stop when status is finished or failed.
Provide callback_url at the request top level to receive the terminal result instead of polling.

Related Models

Kling 2.6 Motion ControlTransfer motion from a source video to a character image while preserving identity.

Wan 2.6Create 1080p videos with text, image, or video-guided workflows.

Hailuo 02Generate text-led or image-guided clips with 768p and 1080p options.

Seedance 1.0 ProBuild multi-shot videos with prompt control and first-frame guidance.

Kling 2.6Generate video with synchronized dialogue, effects, and ambient audio.

Wan AnimateAnimate a character from reference motion while retaining visual identity.

Sora 2Create videos with physical motion, synchronized audio, and image input.

Sora 2 ProUse the higher-resolution Sora workflow for polished video output.

Veo 3.1Generate 1080p scenes with native audio and extended creative controls.

Grok Imagine Video 1.5Turn text, a first frame, or reference images into videos up to 1080p.

Grok ImagineMove between image generation and video creation in one visual workflow.

Seedance 2Guide video generation with text, frames, and multimodal references.

Frequently Asked Questions about MiniMax H3 Text to Video API

What is the MiniMax H3 Text-to-Video API?

MiniMax H3 Text-to-Video is MiniMax's text-driven video generation model. You describe the scene, action, and camera movement in a prompt, and it returns a fixed 2K video lasting 5–15 whole seconds, making it useful for concept shots, ads, and social clips that do not need source media.

How do I call the MiniMax H3 Text-to-Video API?

Send a POST request to /api/generate/submit with a Bearer API key, model set to minimax/h3/text-to-video, and generation fields inside input. The API returns a task_id immediately; runnable cURL, JavaScript, and Python examples appear in the API tab, with the full schema at https://docs.vidgo.ai/api-manual/video-series/minimax-h3-text-to-video.

How much does MiniMax H3 Text-to-Video cost?

The API costs 21 credits per generated second. A 5 second video costs 105 credits, a 10 second video costs 210 credits, and a 15 second video costs 315 credits. Before submission, the Run button shows the calculated USD price for the current duration.

What inputs does MiniMax H3 Text-to-Video accept?

Key inputs are prompt, duration, resolution, and aspect_ratio. The prompt must contain 1 to 2,000 characters, duration is an optional whole second from 5 to 15, resolution is fixed at 2K, and MiniMax H3 Text-to-Video API does not accept source media. The parameter table above lists requirements, defaults, and all six allowed aspect ratios.

How do I get the generated video?

Poll GET /api/generate/status/{task_id} with the returned task_id until status is finished or failed. When finished, read the video URL from data.files[].file_url; alternatively, include callback_url in the submit request to receive the final result asynchronously.

Which MiniMax H3 API mode should I choose?

Use Text-to-Video when a prompt should define the entire scene. Choose Image-to-Video for a required start frame and optional end frame, or Reference-to-Video when multiple images, videos, or audio clips should guide the result.