MiniMax H3 SH

MiniMax H3 SH is the Open Weights edition of the H3 video family. It provides three separate models for text, first/last frames, and multimodal references, with native stereo audio and 3–15 second output.

Models and endpoint

All three use POST https://api.aivideoapi.ai/v1/videos/generations. The request body contains model, input, and an optional callback_url.

Shared input parameters

Text and reference modes also accept aspect_ratio: 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9, or 9:21. Image-to-video follows the first image and does not accept aspect_ratio.

Use the unified media fields described below. Do not send image, last_image, reference_images, reference_videos, or reference_audios. All media URLs must be accessible public HTTP(S) URLs. Duration must be a JSON integer; strings, fractions, and values outside 3–15 are rejected before charging.

Generate from text

Use minimax-h3-sh/text-to-video with a prompt and output controls. This model does not accept reference media.

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-sh/text-to-video",
    "input": {
      "prompt": "A slow tracking shot through a sunlit forest. Audio: birdsong and gentle wind.",
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "16:9",
      "seed": -1
    }
  }'

Animate first and last frames

Use minimax-h3-sh/image-to-video. image_urls is required and contains one or two URLs: the first image sets the opening frame; an optional second image sets the final frame. Both frame images are free. This mode does not accept video or audio references or aspect_ratio.

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-sh/image-to-video",
    "input": {
      "prompt": "The camera moves forward as the room fills with sunlight. Audio: quiet room tone.",
      "image_urls": ["https://example.com/first.png", "https://example.com/last.png"],
      "resolution": "768p",
      "duration": 8
    }
  }'

Generate from references

Use minimax-h3-sh/reference-to-video with at least one reference image, video, or audio.

Reference videos share a total 15-second processing budget. Longer inputs are accepted and trimmed across the references. Their embedded soundtracks are used automatically and do not incur a separate audio fee.

Address references in the prompt as <Picture 1> through <Picture 9>, <Video 1> through <Video 3>, and <Audio 1> onward. Numbering follows input order within each type. Video soundtracks occupy the earliest audio slots, so standalone audio numbering follows them; use the video tag when referring to that video's soundtrack.

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-sh/reference-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "Use the character from <Picture 1> and camera movement from <Video 1>. Audio: soft city ambience.",
      "image_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/movement.mp4"],
      "audio_urls": [],
      "resolution": "540p",
      "duration": 10,
      "aspect_ratio": "16:9"
    }
  }'

Pricing

One credit is worth $0.005. These are standard prices before any account multiplier.

• Text / image: requested duration × output rate. First and last frame images are free.
• Reference: (requested duration + billable reference seconds) × reference rate + 4 × image count + 4 × standalone audio count.
• Billable reference seconds: min(15, sum of detected video durations). Sum the actual seconds, including fractional seconds, and cap the total at 15 seconds; no input videos means zero.
• Native generated audio is included. A reference video's soundtrack does not increase the standalone audio count.

For example, a 10-second 480p reference output with 2 images and a 5-second reference video costs 158 credits ($0.79). A 5-second 480p output with one 5.167-second reference video costs 101.67 credits: (5 + 5.167) × 10. Two such references are billed for their actual total of 10.334 seconds and cost 153.34 credits: (5 + 10.334) × 10. Three such references are capped at 15 input seconds and cost 200 credits with that output.

The output is charged by the requested integer duration. The model's frame grid can produce a slightly longer file (about 5.2 seconds for a 5-second request); this does not trigger an additional charge or duration settlement. The complete base charge is rounded to two decimals, then the account multiplier is applied and rounded to two decimals again.

Task queries and refunds

Creation returns a platform task ID:

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

Poll GET https://api.aivideoapi.ai/v1/tasks/{taskId} with the same Bearer authorization. States are pending, processing, completed, and failed. Completed tasks expose the video in output.urls:

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 40,
  "output": {
    "urls": ["https://file.aivideoapi.ai/videos/example.mp4"]
  }
}

Credits are reserved once before submission. A confirmed failed task is refunded once. An uncertain submission remains pending reconciliation; a successful generation retains its charge while video delivery or callbacks retry. Successful tasks must never be refunded by a later error path. No output-duration adjustment is applied, and submitted tasks cannot be cancelled.

Callback notifications

All three models support callbacks. Add callback_url at the top level of the creation request, alongside model and input. Use a publicly accessible HTTP(S) URL; HTTPS is recommended.

{
  "model": "minimax-h3-sh/text-to-video",
  "callback_url": "https://your-server.com/webhook",
  "input": {
    "prompt": "A sunlit forest with birdsong",
    "resolution": "480p",
    "duration": 5
  }
}

When the task completes or fails, the platform sends a JSON POST request to that URL. The pending and processing states do not trigger callbacks.

Callback headers

Successful task

X-Event is task.completed. Read the video URLs from output.urls. All timestamps are Unix timestamps in seconds.

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 40,
  "created_at": 1789516800,
  "completed_at": 1789516920,
  "output": {
    "urls": ["https://file.aivideoapi.ai/videos/example.mp4"]
  }
}

Failed task

X-Event is task.failed. The error object describes the failure. Reserved credits are refunded when the task is confirmed failed.

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 0,
  "created_at": 1789516800,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

Acknowledgment and retries

After saving the notification, promptly return an HTTP 2xx response. Each delivery times out after 10 seconds. Connection failures, timeouts, and non-2xx responses trigger retries, for up to 3 attempts including the initial delivery:

Retries run on a scheduled job, so actual delivery may occur slightly later. Make your handler idempotent using the task id and event type to avoid repeating business operations when a notification arrives more than once.

A callback delivery failure does not change the video task result or refund a successful task. If no notification arrives, query GET /v1/tasks/{taskId} for the result. See the Callback Guide for more information.

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.