MiniMax H3 Fast

MiniMax H3 Fast is a native multimodal video model supporting text-to-video, first/last-frame animation, and reference-guided generation with images, videos, and audio. It supports 5–15 second videos at 480p through the standard AI Video API task interface.

Model

Use minimax-h3-fast with:

POST https://api.aivideoapi.ai/v1/videos/generations

Pricing

Only requested output-video seconds are billed. All input images, reference videos, and reference audio are free, including the sixth through ninth reference images.

Only 480p is available and it is the default resolution.

Request Body

Input Parameters

Only public HTTP(S) media URLs are accepted. mm_file:// references and Data URIs are not supported by this gateway.

Parameter Constraints

Aspect ratio aspect_ratio

The public aspect_ratio field maps to MiniMax's upstream ratio. Supported values are adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16, with different rules for each generation mode:

Text-to-video defaults to 16:9 when aspect_ratio is omitted. Supplying adaptive for text-to-video returns a validation error.

Generation mode and media combinations

• Every request requires a non-empty prompt, counted by characters, with a maximum length of 7000 characters.
• duration must be a positive integer. The documented supported range and Playground controls are 5–15 seconds. The API forwards any positive integer unchanged, including 4 or 16, without enforcing or clamping to that range; acceptance outside the supported range depends on the generation service. Estimation uses the same requested duration.
• first_and_last_frames requires 1–2 images: image_urls[0] is the first frame and image_urls[1], when present, is the last frame. Video and audio references are not allowed in this mode.
• omni_reference supports up to 9 reference images, 3 reference videos, and 3 reference audio files.
• Audio cannot be the only reference medium. When audio_urls is present, include at least one image or video.
• Frame generation and multimodal reference generation are mutually exclusive; do not combine frame images with reference video or audio in one request.
• resolution must be 480p and defaults to 480p. watermark must be a boolean and defaults to false.

Input media limits

MiniMax validates the following file properties upstream. This gateway validates public URLs, item counts, and reference-video duration before submission. Media that violates an upstream limit may be rejected during submission or fail the task.

MiniMax caps the upstream request body at 64 MB. This gateway does not accept Base64, so use public URLs that require no login, have no hotlink protection, and are directly retrievable by MiniMax. The Playground uploader currently accepts JPG, PNG, and WEBP; other officially supported image formats supplied by API URL must still satisfy the table above.

Generation Modes

Text-to-video

Omit all media arrays. The aspect ratio defaults to 16:9; adaptive is not allowed for text-only requests.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-fast",
    "input": {
      "prompt": "An epic space-opera trailer, a lone captain watches the final fleet jump away",
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

First/last-frame video

Set generation_type to first_and_last_frames. image_urls[0] is the first frame and the optional image_urls[1] is the last frame. Video and audio references cannot be combined with this mode. The output ratio follows the frame images.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-fast",
    "input": {
      "prompt": "The camera pushes forward as morning light fills the room",
      "generation_type": "first_and_last_frames",
      "image_urls": [
        "https://example.com/first.png",
        "https://example.com/last.png"
      ],
      "resolution": "480p",
      "duration": 5
    }
  }'

Multimodal reference video

Use omni_reference with any supported combination of images, videos, and audio. Audio requires at least one reference image or video. Omit aspect_ratio to use adaptive.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-fast",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "The character says: Follow the wind and live free, using the reference voice",
      "generation_type": "omni_reference",
      "image_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/motion.mp4"],
      "audio_urls": ["https://example.com/voice.mp3"],
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "adaptive"
    }
  }'

Task Lifecycle

Creation returns the platform task ID:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

Query the task with:

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions are pending → processing → completed or failed. Completed output uses the standard output.urls array. If generation has succeeded but its result is still being delivered, keep polling while the task remains processing.

When available, a completed task includes media usage data at the top-level usage field:

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "credits_consumed": 175.20,
  "model": "minimax-h3-fast",
  "created_at": 1785685446,
  "completed_at": 1785685956,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/02/output_aigc.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Fast",
      "resolution": "480p",
      "duration": 15,
      "ratio": "16:9",
      "task_type": "generation"
    }
  },
  "usage": {
    "total_seconds": 15,
    "input_seconds": 0,
    "output_seconds": 15,
    "input_image_count": 0
  }
}

When available, usage is returned after successful completion in both task-query responses and task.completed callbacks. It contains media measurements only; input seconds and image counts never add a charge. credits_consumed reports the finalized customer charge, and remains 0 while the task is in progress or after a confirmed failure has been refunded. A successful 15-second request at the default account multiplier reports 175.20 credits.

Callback

Pass callback_url when creating a task to receive task.completed or task.failed events. The callback body matches the corresponding terminal task-query response, including public usage when available. Return a 2xx response to acknowledge receipt; use GET /v1/tasks/{taskId} to retrieve status if callback delivery fails. See the Callback Guide for headers and retries.

Create a task with a callback

Submit the following body to POST /v1/videos/generations. The platform sends a POST request to callback_url when the task completes or fails:

{
  "model": "minimax-h3-fast",
  "callback_url": "https://your-server.com/webhook",
  "input": {
    "prompt": "A fast cinematic tracking shot through a neon city at night",
    "resolution": "480p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}

Headers

Completed callback example

X-Event: task.completed. The following body shows a successful 5-second video at the default account multiplier:

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "model": "minimax-h3-fast",
  "credits_consumed": 58.40,
  "created_at": 1789171200,
  "completed_at": 1789171320,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/09/12/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Fast",
      "resolution": "480p",
      "duration": 5,
      "ratio": "16:9",
      "task_type": "generation"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

Failed callback example

X-Event: task.failed. Example body:

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "failed",
  "model": "minimax-h3-fast",
  "credits_consumed": 0,
  "created_at": 1789171200,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

Callbacks may be delivered more than once. Handle them idempotently using the task id.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

• The key does not start with sk-
• The key has been disabled or deleted
• The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

• The input contains sensitive or prohibited content
• The provider is temporarily unavailable
• The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.