MiniMax H3 Max

MiniMax H3 Max is a fast video generation model for text-to-video and first/last-frame image-to-video. It generates 5–15 second videos at 480p or 768p through the standard asynchronous task API.

Model and endpoint

Use minimax-h3-max with:

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

Pricing

Only generated output video is billed. Input images are free.

A 5-second 480p request costs 5 × 12.7 = 63.5 credits. A 5-second 768p request costs 5 × 19.23 = 96.15 credits. The same prices apply to text-to-video and image-to-video because input images do not add any charge.

Credits are pre-charged before submission. A confirmed failed task is refunded once. If submission may have reached the generation service but no authoritative response is available, the task remains pending and the pre-charge is retained for reconciliation rather than being refunded incorrectly.

Request body

Input parameters

video_urls, audio_urls, omni_reference, 2k, and a 4-second duration are not supported.

Generation modes

Text-to-video

Omit generation_type. Supported ratios are 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16; the default is 16:9. adaptive is not accepted for text-to-video.

If image_urls is included while generation_type is omitted, it may contain any number of string entries, but every entry is ignored. The images are not validated, fetched, stored, sent to the generation service, or billed.

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-max",
    "input": {
      "prompt": "A fast cinematic tracking shot through a neon city at night",
      "resolution": "768p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

First/last-frame image-to-video

Set generation_type to first_and_last_frames. Provide one image for the first frame or two images for first and last frames. The output ratio is always derived from the images, so any otherwise valid aspect_ratio is ignored and normalized to 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-max",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "The camera moves forward as daylight fills the room",
      "generation_type": "first_and_last_frames",
      "image_urls": [
        "https://example.com/first.png",
        "https://example.com/last.png"
      ],
      "resolution": "480p",
      "duration": 8
    }
  }'

Frame images must use public HTTP(S) URLs. The upstream media limits are JPG, JPEG, PNG, WEBP, HEIC, or HEIF; no more than 30 MB per file; width and height from 256 to 5760 pixels; and a width/height ratio from 0.4 to 2.5.

Create response

The create endpoint returns a platform task ID. Save data.taskId for subsequent task queries:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1"
  }
}

Query task

Use the taskId from the create response:

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

Status transitions are pending → processing → completed or failed.

Pending

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "pending",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "estimated_seconds": 300
}

Processing

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "processing",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "progress": null
}

Completed

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-max",
  "credits_consumed": 96.15,
  "created_at": 1788066000,
  "completed_at": 1788066120,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/30/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Max",
      "resolution": "768p",
      "duration": 5,
      "ratio": "16:9"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

output.urls contains the generated video URL. usage is included only when media usage is returned by the generation service. Input usage does not add any H3 Max customer credit charge.

Failed

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

credits_consumed is the task's finalized customer credit charge. It is 0 while the task is in progress and after a confirmed failure has been refunded; completed tasks report the actual charge. A confirmed failed task is refunded only once.

GET /v1/tasks/{taskId} is the authoritative source for task status. This model does not support cancellation.

Successful task responses may include usage.total_seconds, usage.input_seconds, usage.output_seconds, and usage.input_image_count. These fields report media usage only; customer credits are always calculated from the requested output duration and resolution, with no input-image charge.

Callback

Pass callback_url when creating the task. The platform sends a POST request when the task reaches the completed or failed terminal state:

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

Headers

Completed callback

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-max",
  "credits_consumed": 96.15,
  "created_at": 1788066000,
  "completed_at": 1788066120,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/30/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Max",
      "resolution": "768p",
      "duration": 5,
      "ratio": "16:9"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

Failed callback

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

The callback body matches the corresponding terminal response from the query task endpoint. Return any 2xx status to acknowledge delivery. If the URL is unreachable or returns a non-2xx status, the platform makes up to three delivery attempts: immediately, then approximately 3 minutes and 10 minutes after failures.

If all callback attempts fail, continue using GET /v1/tasks/{taskId} as the fallback for final status. See the Callback Guide for complete header and retry details.

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.