How to Use the MiniMax H3 API: Text-to-Video and Image-to-Video Examples

MiniMax H3 can generate a short video from a prompt or animate a supplied first frame. But a useful MiniMax H3 API example needs more than a request body: you also need to know which parameters PiAPI exposes, how asynchronous polling works, what a successful task costs, and where the model can still ignore instructions.

This guide is for developers and creative teams integrating MiniMax H3 through PiAPI. We ran three paid tasks on August 10, 2026, and preserved the prompts, task IDs, timings, charges, input asset, and output metadata. We kept the imperfect result rather than paying for a cleaner replacement and hiding the limitation.

Direct answer: MiniMax H3 through PiAPI is an asynchronous video-generation API for text-to-video and first-frame image-to-video. It returns an MP4 with stereo audio and currently supports 512p or 768p output, 5–15 second requests, and 16:9, 9:16, or 1:1 aspect ratios.

Evidence note: “Documented” facts below come from the PiAPI MiniMax Generate Video API documentation verified on August 10, 2026. “Observed” results come from our three original PiAPI tasks. This small example set is not a benchmark.

Key takeaways

• The PiAPI model identifier is Qubico/minimax-h3.
• Use txt2video for prompt-only generation and img2video when supplying a first frame.
• PiAPI exposes 512p or 768p, 5–15 second requests, and 16:9, 9:16, or 1:1 framing.
• All three inspected MP4 files contained AAC stereo audio.
• Pricing is $0.03 per second at 512p and $0.05 per second at 768p.
• Three successful 5-second tasks cost $0.55, with no retries or failures.
• Generation is asynchronous: create a task, save its ID, poll the task endpoint, and then download the completed MP4.

Table of contents

1. What is the MiniMax H3 API?
2. Requirements and supported parameters
3. How to use MiniMax H3 with PiAPI
4. Text-to-video example
5. Image-to-video example
6. A complex 768p vertical example
7. Pricing and measured cost
8. Native audio
9. Limitations and troubleshooting
10. When to use MiniMax H3 through PiAPI
11. FAQ

What is the MiniMax H3 API?

MiniMax H3 is a video-generation model from MiniMax, described in the company’s official H3 overview. Through PiAPI, developers can access a specific supported subset of its video capabilities using PiAPI’s task API.

The distinction matters. Upstream MiniMax material may discuss a broader H3 capability set, but the PiAPI endpoint covered here has a narrower documented contract:

This article does not treat upstream claims such as 2K output, multi-shot generation, video-to-video transfer, or generalized editing as PiAPI features. If those capabilities are not present in the current PiAPI request schema, they should not be promised in a PiAPI implementation.

You may also encounter the name “Hailuo H3” in product and search results. PiAPI also provides a separate Hailuo API product path. For this integration, the important implementation detail is the exact PiAPI model identifier Qubico/minimax-h3. Use the identifier and feature set in the current PiAPI documentation rather than inferring API behavior from product naming.

MiniMax H3 API requirements and supported parameters

You need:

1. A PiAPI account and API key.
2. An HTTP client such as cURL, JavaScript fetch, or Python requests.
3. A public JPG/PNG URL or a base64 data URI for img2video.
4. A polling loop because video generation does not finish inside the initial POST request.

The current PiAPI MiniMax API documentation defines the following request fields:

Text-to-video versus image-to-video

Keep the prompt concrete: name the subject and setting, main action, camera motion, visual treatment, desired sound, and exclusions such as speech, music, logos, or readable text.

Exclusions are instructions, not guarantees. Our complex example requested “no readable signs,” but the output still contained pseudo-readable menu lettering.

How to use the MiniMax H3 API with PiAPI

The complete flow has six steps:

1. Open the MiniMax H3 workspace, create a PiAPI API key, and keep it outside source control.
2. Send a creation request to POST https://api.piapi.ai/api/v1/task.
3. Save the returned task_id.
4. Poll GET https://api.piapi.ai/api/v1/task/{task_id} at a reasonable interval.
5. Stop on a completed, failed, or client-side timeout condition.
6. Download the completed MP4 and validate its video, audio, and duration.

Quick cURL request

Set your API key in an environment variable instead of pasting it into source control:

export PIAPI_API_KEY="your-api-key"

On PowerShell:

$env:PIAPI_API_KEY = "your-api-key"

Then submit a text-to-video task:

curl --request POST \
  --url https://api.piapi.ai/api/v1/task \
  --header "Content-Type: application/json" \
  --header "x-api-key: $PIAPI_API_KEY" \
  --data '{
    "model": "Qubico/minimax-h3",
    "task_type": "txt2video",
    "input": {
      "prompt": "A ceramic coffee cup beside a rain-streaked window, slow camera push-in, warm light, realistic materials, rain ambience, no speech, no music, no readable text.",
      "resolution": "512p",
      "duration": 5,
      "aspect_ratio": "16:9",
      "seed": 0
    },
    "config": {
      "service_mode": "public"
    }
  }'

The creation response returns a task object with a task_id and an initial status such as pending. It does not immediately return a finished video.

Complete JavaScript example with polling

The code below submits a task, waits between polls, handles completed and failed states, and returns the output URL:

const API_BASE = "https://api.piapi.ai/api/v1";
const API_KEY = process.env.PIAPI_API_KEY;

if (!API_KEY) {
  throw new Error("PIAPI_API_KEY is not set");
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function piapiRequest(path, options = {}) {
  const response = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
      ...options.headers,
    },
  });

  const payload = await response.json();

  if (!response.ok || payload.code !== 200) {
    throw new Error(
      `PiAPI request failed: ${payload.message || response.statusText}`
    );
  }

  return payload.data;
}

async function createMiniMaxH3Task(input) {
  return piapiRequest("/task", {
    method: "POST",
    body: JSON.stringify({
      model: "Qubico/minimax-h3",
      task_type: input.image ? "img2video" : "txt2video",
      input: {
        prompt: input.prompt,
        image: input.image || "",
        resolution: input.resolution || "512p",
        duration: input.duration || 5,
        aspect_ratio: input.aspectRatio || "16:9",
        seed: input.seed ?? 0,
      },
      config: {
        service_mode: "public",
      },
    }),
  });
}

async function waitForTask(
  taskId,
  { pollIntervalMs = 5000, timeoutMs = 15 * 60 * 1000 } = {}
) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const task = await piapiRequest(`/task/${taskId}`, {
      method: "GET",
    });

    if (task.status === "completed") {
      // Our August 10 tests returned output.video_url.
      // The current documentation sample shows output.video.
      const videoUrl = task.output?.video_url || task.output?.video;

      if (!videoUrl) {
        throw new Error("Task completed without a video URL");
      }

      return { task, videoUrl };
    }

    if (task.status === "failed") {
      throw new Error(
        task.error?.message || `Task ${taskId} failed`
      );
    }

    await sleep(pollIntervalMs);
  }

  throw new Error(`Task ${taskId} did not finish before the timeout`);
}

const createdTask = await createMiniMaxH3Task({
  prompt:
    "A cinematic close-up of a ceramic coffee cup beside a rain-streaked window. Slow camera push-in, warm light, realistic materials, rain ambience, no speech, no music, no readable text.",
  resolution: "512p",
  duration: 5,
  aspectRatio: "16:9",
  seed: 0,
});

console.log("Created task:", createdTask.task_id);

const result = await waitForTask(createdTask.task_id);
console.log("Video URL:", result.videoUrl);

Store the returned MP4 promptly. Temporary output URLs may not be suitable as permanent publication storage.

MiniMax H3 text-to-video API example

For the baseline test, we chose a simple scene with one main subject, restrained camera motion, visible rain, and environmental sound.

Prompt

A cinematic close-up of a handmade ceramic coffee cup on a dark wooden table beside a rain-streaked window. Steam rises naturally from the coffee while soft rain taps the glass and a low distant thunder roll is heard. The camera makes a slow, steady push toward the cup. Warm interior light, realistic materials, shallow depth of field. No speech, no music, no readable text.

Settings and task evidence

Example 1 output: MiniMax H3 text-to-video at 512p from the coffee-and-rain prompt. Requested duration: 5 seconds. Charged cost: $0.15.

The cup, handle, window, and tabletop remain stable in the representative frames, and the rain-streaked glass stays visible. The restrained change suits the requested push-in, although the movement is subtle. Steam is not clear in the sampled frames, so the article should not present it as a strong success without a closer full-motion review.

Verdict: Use this as the clean baseline for the request and polling walkthrough.

MiniMax H3 image-to-video API example

Image-to-video uses the supplied image as the first frame. PiAPI accepts a public JPG/PNG URL or a base64 data URI. For this test, we created a publication-safe 576×1024 JPEG of an unbranded teal perfume bottle. The generation helper uploaded it to a temporary URL before submitting the PiAPI task.

Image-to-video request

const createdTask = await createMiniMaxH3Task({
  prompt:
    "The camera slowly moves in a gentle half-orbit around the teal glass perfume bottle while the sheer fabric in the background drifts subtly in a light breeze. Keep the bottle shape, cap, color, pedestal, and overall composition consistent with the first frame. Add quiet room ambience, a soft fabric rustle, and one delicate glass chime near the end. No speech, no music, no text, no logo.",
  image: "https://your-public-host.example/perfume-first-frame.jpg",
  resolution: "512p",
  duration: 5,
  aspectRatio: "9:16",
  seed: 0,
});

If you prefer a data URI, construct it without logging the full encoded payload:

import { readFile } from "node:fs/promises";

const imageBytes = await readFile("./perfume-first-frame.jpg");
const imageDataUri =
  `data:image/jpeg;base64,${imageBytes.toString("base64")}`;

// Pass imageDataUri as the image value.

Settings and task evidence

Example 2 output: The 512p image-to-video result preserved the bottle, while the moving fabric became more prominent than requested. Charged cost: $0.15.

The bottle shape, teal color, cap, pedestal, and central placement remain highly consistent across the sampled frames. The background fabric moves more than the requested subtle drift and increasingly crosses in front of the product. The requested half-orbit is not obvious in the contact sheet.

Verdict: Use this to show first-frame preservation, while calling out the distracting fabric motion.

A complex 768p vertical example

Our third task increased scene complexity rather than pretending to be a controlled 512p-versus-768p comparison. It combined two people, a hand-to-hand object transfer, background activity, steam, reflections, camera movement, signage, and layered sound instructions.

Prompt

A handheld cinematic shot at a busy night-market drink stall. A vendor passes a steaming paper cup across the counter to a customer, both hands remaining anatomically natural and the cup staying consistent during the handoff. Neon reflections shimmer on the wet counter while steam rises and people move softly in the background. The camera tracks sideways at walking speed. Native audio: gentle crowd chatter, a drink machine hiss, cup movement on the counter, and light rain. No music, no readable signs, no logos.

Settings and task evidence

Example 3 output: A complex 768p vertical handoff. The cup and hands stayed mostly coherent, but generated menu text appeared despite the text-avoidance instruction. Charged cost: $0.25.

The cup stays visually consistent through the sampled handoff, and the interaction between the vendor’s gloved hand and the customer’s hand is mostly coherent. Steam, reflections, and the busy stall environment are visible. However, the output contains prominent pseudo-readable menu and stall lettering even though the prompt explicitly prohibited readable signs and logos.

Verdict: Keep this as limitation evidence: negative text instructions did not reliably suppress generated signage.

This single task also took longer than either 512p task in our three-run set. That is an observation, not proof that resolution caused the difference; prompt complexity, queue conditions, and other service factors were not controlled.

MiniMax H3 API pricing and cost examples

PiAPI documents per-second pricing based on requested resolution. The rates below were verified against the MiniMax Generate Video documentation and the three successful charges on August 10, 2026. Check the PiAPI pricing page for broader account and plan details.

That produces the following estimated successful-task costs:

PiAPI states that successful tasks are charged. Preserve every task record anyway so failures, refunds, retries, or moderation outcomes are not silently excluded from later cost analysis.

What our example set cost

All three attempts completed successfully, and all three were retained as usable and publication-approved evidence. There were no failed or retried tasks. The rounded cost per usable or approved output was $0.18. The resulting 100% usable and approval rates describe only this three-task evidence set, not a general model success rate.

Does MiniMax H3 generate native audio?

Yes. PiAPI documents native stereo audio muxed into the returned MP4 rather than requiring a separate audio-generation request.

All three files we downloaded contained:

• H.264 video
• AAC audio
• Two audio channels with a stereo layout
• A 32 kHz audio sample rate

We also extracted the audio tracks successfully with FFmpeg, confirming that the streams were decodable. However, stream presence is not the same as a listening evaluation. Do not claim that the requested rain, glass chime, crowd, machine hiss, or synchronization was accurate until the clips receive a deliberate listening pass.

For production automation, inspect both streams after download:

ffprobe -v error \
  -show_streams \
  -show_format \
  -of json \
  output.mp4

This catches cases where a download exists but the expected media streams or duration do not.

Limitations and troubleshooting

The API is asynchronous

The POST request creates work; it does not wait for the final MP4. Save task_id, poll with a delay, and stop on completion, failure, or a client-side timeout. Without a timeout, a network or task-state problem can leave a worker polling indefinitely.

Handle both documented and observed output fields

Our completed task records returned the URL in output.video_url, while the current documentation sample displays output.video. Treat the documentation as the contract, but make the client tolerant during integration:

const videoUrl = task.output?.video_url || task.output?.video;

Log unexpected response shapes without logging your API key or an entire base64 input.

Validate image inputs before submission

For img2video, use JPG or PNG, stay within the documented 4,096 px limit, and ensure the API service can fetch the URL. Browser access alone is not enough when authentication, expiring signatures, or hotlink protection blocks server-side retrieval.

If using a data URI, confirm the MIME type matches the file and avoid passing raw base64 without the data:image/...;base64, prefix.

Check prompt length before submitting

PiAPI documents a 2,000-character prompt limit. Validate the final rendered string before submission, especially when prompts are assembled from templates.

Returned duration can differ slightly

Each of our three 5-second requests produced a file with a measured duration of 5.167 seconds. Budget from requested duration, but validate actual duration when a downstream editor, timeline, or ad platform requires exact timing.

Negative prompt instructions are not guarantees

The night-market example requested no readable signs or logos. Generated pseudo-text still appeared prominently. For brand-sensitive work:

• Avoid compositions dominated by signs, menus, labels, or screens.
• Use a clean first-frame image when layout control matters.
• Reserve space for real typography to be added in post-production.
• Review every frame, and add factual claims or prices as real typography in post-production.

Product-background motion can become too strong

In the perfume example, the bottle stayed consistent but the fabric became more prominent than requested and crossed the product. Use restrained motion language, specify that the product must remain unobstructed, and plan for review or post-production rather than assuming “subtle” will be interpreted exactly.

Seed does not prove determinism

We recorded seed 0 for reproducibility of the request record, but we did not run matched repeats. Do not promise identical results from the same seed without controlled evidence.

Do not infer performance from three tasks

The 768p complex task took 229.65 seconds from creation to completion, compared with 129.12 and 150.47 seconds for the two 512p tasks. Resolution may be one factor, but the prompts, scene complexity, and service conditions differed. These timings are transparent examples, not a latency guarantee.

Store outputs promptly

Download successful MP4 files to storage you control. Keep the original request, completed response, task ID, timestamps, charge, and local filename together so you can reproduce captions and cost calculations later.

Why this guide does not show 2K or multi-shot output

The PiAPI endpoint documented and tested here exposes 512p and 768p text-to-video and first-frame image-to-video. Broader MiniMax capabilities should not be represented as available through PiAPI until the PiAPI documentation and request schema support them.

When should you use MiniMax H3 through PiAPI?

Based on the documented endpoint and these three examples, MiniMax H3 through PiAPI is worth testing for:

• Short-form video concepts in landscape, vertical, or square formats
• Programmatic text-to-video prototyping
• Animating a controlled first frame
• Product or lifestyle motion studies where the source image anchors composition
• Workflows that benefit from video and generated audio in one MP4
• Batch systems that can create, poll, validate, download, and review asynchronous tasks

Do not treat it as a one-step production solution when you need guaranteed typography, exact brand-layout preservation, frame-perfect duration, proven seed determinism, or output that can publish without review. Generation should sit inside a pipeline that validates the media and includes human approval.

For broader examples of how teams can apply MiniMax video generation to ads, storytelling, and e-commerce, see the existing Hailuo video use-case guide.

After reviewing the supported parameters, evidence, and expected cost, try MiniMax H3 through PiAPI.

Frequently asked questions

Conclusion

Treat MiniMax H3 through PiAPI as an asynchronous media pipeline: submit Qubico/minimax-h3, save the task ID, poll with a timeout, download the MP4, and validate both streams.

The three tasks provided a stable text-to-video baseline, strong first-frame preservation, and a useful failure where generated signage ignored a text-avoidance instruction. They also matched the documented 512p and 768p rates, with $0.55 in successful charges. Preserve the request, task evidence, cost, validation, and an honest account of what each output missed.

Ready to test the workflow? Try MiniMax H3 through PiAPI, or open the API documentation to use the current request schema.