How to Use the MiniMax H3 Max API for Text and Image to Video

This guide takes the shortest path to a successful request and then adds the validation, polling, callback, storage, and fallback decisions required for production. Until the dedicated H3 Max documentation pages are published, verify exact fields against the live route contract on the model page.

Create an EvoLink API key, check the live estimate on the MiniMax H3 Max model page, and keep the H3 Max vs H3 guide nearby if your workflow may need 2K or broader references.

Prerequisites

Before making the first request, confirm:

Choose the Correct H3 Max Model ID

Step 1: Make a Text-to-Video Request

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

The main T2V parameters are:

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

Step 2: Make a First/Last-Frame Image-to-Video Request

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

Each supplied image must use a directly accessible HTTP(S) URL and follow the current contract:

• JPG, JPEG, PNG, WEBP, HEIC, or HEIF.
• Maximum 30 MB per image.
• Width and height between 256 and 5,760 pixels.
• Width-to-height ratio from 0.4 through 2.5.
• At most one first frame and one last frame.
• Complete JSON body no larger than 64 MB; Base64 and mm_file:// are not accepted.

Step 3: Poll the Task Status

Query the task with the same Bearer token:

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

A simple polling policy should use bounded exponential backoff with jitter rather than querying continuously. For example: start near two seconds, grow toward 10–15 seconds, stop at an application-defined deadline, and allow a later worker to resume using the stored task ID. The API contract does not provide cancellation for H3 Max, so a client timeout should not be mistaken for an upstream cancellation.

Step 4: Add a Callback for Production

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

The current EvoLink contract requires HTTPS, rejects private IP destinations, waits up to 10 seconds, and retries a failed callback up to three times. Your handler should:

1. Authenticate the request using the verification mechanism configured by your application.
2. Use the task ID as the idempotency key.
3. Return a 2xx response quickly.
4. Move downloads and heavy post-processing to a queue.
5. Reconcile callback state with the task endpoint before final customer delivery when needed.

Keep polling available as a recovery path. Webhooks can be delayed, rejected by network policy, or processed twice by application infrastructure.

Validate Requests Before Submission

Handle Errors by Category

Separate HTTP errors from asynchronous task failures. A create call can succeed while the generation later fails. Log the task ID, route, input class, duration, quality, final status, error code, retry count, and fallback result without logging secrets or sensitive source URLs.

Design the Production Handoff

Store the request and task relationship

Create your own job ID before submission. Store the EvoLink task ID, model ID, normalized parameters, customer/workspace ID, timestamps, and delivery state. This makes retry, audit, and support possible even if a worker restarts.

Download completed results promptly

H3 Max result URLs are available for 24 hours. Copy accepted results into durable storage and record the checksum or object key. Do not make the temporary source URL the permanent customer asset.

Make retries explicit

Do not submit a new generation because a polling request timed out. First query the stored task ID. Only create a new task when the original reached a terminal failure and your retry policy allows another billed attempt.

Route incompatible jobs before the call

Measure accepted output

Track:

• task success rate and completion latency;
• first-pass acceptance and retry rate;
• cost per accepted clip;
• prompt, identity, and keyframe adherence;
• moderation and invalid-request rate;
• fallback frequency and recovery rate;
• download completion before URL expiry.

Common Integration Mistakes

Go-Live Checklist

1. The API key is server-side and can be rotated.
2. T2V and I2V use separate validation schemas.
3. Duration, quality, aspect ratio, and image limits are enforced locally.
4. The creation response id is stored before the worker exits.
5. Polling uses bounded backoff and can resume.
6. Callback handling is idempotent and polling remains available.
7. Completed MP4 files are copied within 24 hours.
8. Logs separate request errors, task failures, and review rejection.
9. Pricing comes from the current model page or pricing service, not a hard-coded blog value.
10. H3 and one independent fallback are tested for incompatible or failed jobs.

Frequently Asked Questions

What endpoint does MiniMax H3 Max use on EvoLink?

Which model ID should I use?

Is the H3 Max API synchronous?

Can I generate a four-second H3 Max video?

No. The supported duration is an integer from 5 through 15 seconds. MiniMax H3, not H3 Max, supports the four-second lower bound on EvoLink.

Can I use only a last frame?

Yes. The image-to-video model accepts first-frame-only, last-frame-only, and first-and-last-frame requests.

Can I send Base64 images?

Does image-to-video accept an aspect ratio?

Do not send one. The output follows the supplied frame ratio. Prepare the source frame for the intended delivery format.

How long do result URLs remain valid?

Twenty-four hours. Copy completed MP4 files to durable storage as part of the delivery workflow.

Where should I check current pricing?

Use the live pricing section and estimator on the H3 Max product page. Avoid hard-coding a blog rate into production budgeting.

API References and Verification Scope

• EvoLink MiniMax H3 Max model page and live route contract
• EvoLink asynchronous task-status reference
• MiniMax official Video Generation V2 documentation