MiniMax H3

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

Model

Use minimax-h3 with:

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

Pricing

• The first 5 input images are free. Each image after the fifth costs 7.69 credits.
• Reference audio is free.
• Reference video duration is detected by the server and rounded down after summing all reference videos.
• Credits are pre-charged before submission and fully refunded if generation fails.

For example, a default 5-second 2K text-to-video request costs 153.85 credits. A 5-second 2K output with 12 seconds of reference video costs (5 + 12) × 30.77 = 523.09 credits.

Both 2k and 768p are currently available. The default resolution is 2k.

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:

MiniMax requires text-to-video requests to explicitly specify a fixed ratio. For compatibility with existing requests, this gateway fills in 16:9 when a text-only request omits aspect_ratio; new integrations should still send a fixed ratio explicitly. Supplying adaptive explicitly 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 an integer from 4 through 15.
• 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 defaults to 2k; both 2k and 768p are currently available. 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",
    "input": {
      "prompt": "An epic space-opera trailer, a lone captain watches the final fleet jump away",
      "resolution": "2k",
      "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",
    "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": "2k",
      "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",
    "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": "2k",
      "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. By default, the MiniMax provider URL is returned directly without being copied to platform storage.

A completed task includes MiniMax usage data at the top-level usage field:

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

The usage object is available after successful completion in both task-query responses and task.completed callbacks. It contains usage measurements only and does not expose internal upstream cost data.

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.