# MiniMax H3 Max

> Top-tier MiniMax H3 Max video from text, a start/end frame, or reference images, videos, and audio — refer to references in the prompt as Image 1, Video 1, Audio 1, in input order. Up to 15s at 1080p.

## Overview

- **Model ID**: `minimax-h3-max`
- **Workflow**: `minimax/h3-max/video-generation`
- **Provider**: MiniMax
- **Category**: Text → Video (video)
- **Output**: A video URL.
- **Tags**: start/end frame, multi-image input, video input, audio input, 1080p, 5-15 sec
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/minimax/h3-max/video-generation/execute` (vendor's own parameters)
- **Execution**: long-running — use the async submit/poll pair or the SDK, which polls for you
- **Model page**: https://picsart.com/api-platform/models/minimax-h3-max

## Pricing

Rates are in USD. Every row below is an exact rate for the settings it names — the columns are the settings that change the price for this model. Every response reports what was actually charged in `response.usage.credits`.

| Tier | Use case | Rate |
| --- | --- | --- |
| 480p | Image → video, Text → video | $0.03 / sec |
| 768p | Image → video, Text → video | $0.048 / sec |
| 480p | Video → video | $0.05 / sec |
| 768p | Video → video | $0.08 / sec |
| 1080p | Image → video, Text → video | $0.096 / sec |
| 1080p | Video → video | $0.16 / sec |

Published rates. Volume pricing, invoicing and annual agreements: https://picsart.com/api-platform/contact-sales

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('minimax-h3-max', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

Video jobs routinely outrun the sync limit: use async over REST, or the SDK, which polls for you.

### Input parameters

- **`prompt`** (`string`, _required_): Prompt
  - Max length: 50000 characters
- **`startFrame`** (`string`, _optional_): Start Frame
  - Accepts: image URL
- **`endFrame`** (`string`, _optional_): End Frame
  - Accepts: image URL
- **`imageUrls`** (`list<string>`, _optional_): Reference Images
  - Accepts: image URLs (max 9)
- **`videoUrls`** (`list<string>`, _optional_): Reference Videos
  - Accepts: video URLs (max 3), up to 15s
- **`audioUrls`** (`list<string>`, _optional_): Reference Audios
  - Accepts: audio URLs (max 3), up to 15s
- **`resolution`** (`string`, _optional_)
  - Default: `"768p"`
  - Options: `480p`, `768p`, `1080p`
- **`duration`** (`number`, _optional_)
  - Default: `5`
  - Range: 5–15 (step 1)
- **`aspectRatio`** (`string`, _optional_)
  - Default: `"16:9"`
  - Options: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
- **`promptExpansionMode`** (`string`, _optional_): Prompt Expansion
  - Default: `"balanced"`
  - Options: `balanced`, `quality`
- **`seed`** (`number`, _optional_)
  - Default: `-1`
  - Range: -1–2147483647
- **`enableSafetyChecker`** (`boolean`, _optional_): Safety Checker
  - Default: `true`

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 50000,
      "description": "Prompt"
    },
    "startFrame": {
      "type": "string",
      "format": "uri",
      "description": "Start Frame"
    },
    "endFrame": {
      "type": "string",
      "format": "uri",
      "description": "End Frame"
    },
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 9,
      "description": "Reference Images"
    },
    "videoUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "video URL"
      },
      "maxItems": 3,
      "description": "Reference Videos"
    },
    "audioUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "audio URL"
      },
      "maxItems": 3,
      "description": "Reference Audios"
    },
    "resolution": {
      "type": "string",
      "enum": [
        "480p",
        "768p",
        "1080p"
      ],
      "default": "768p"
    },
    "duration": {
      "type": "number",
      "minimum": 5,
      "maximum": 15,
      "multipleOf": 1,
      "default": 5
    },
    "aspectRatio": {
      "type": "string",
      "enum": [
        "adaptive",
        "21:9",
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16"
      ],
      "default": "16:9"
    },
    "promptExpansionMode": {
      "type": "string",
      "enum": [
        "balanced",
        "quality"
      ],
      "default": "balanced",
      "description": "Prompt Expansion"
    },
    "seed": {
      "type": "number",
      "minimum": -1,
      "maximum": 2147483647,
      "default": -1
    },
    "enableSafetyChecker": {
      "type": "boolean",
      "default": true,
      "description": "Safety Checker"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "minimax-h3-max",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "resolution": "768p",
      "duration": 5,
      "aspectRatio": "16:9"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "minimax-h3-max"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "minimax-h3-max"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('minimax-h3-max', {
  prompt: "A serene mountain lake at golden hour, ultra detailed",
  resolution: "768p",
  duration: 5,
  aspectRatio: "16:9"
});

console.log(result.url); // video URL
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "minimax-h3-max",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "resolution": "768p",
      "duration": 5,
      "aspectRatio": "16:9"
    }
  }
}'
```

#### cURL (async: submit, then poll)

```bash
# 1. Submit the job
curl -X POST 'https://api.picsart.com/workflows/v1/models/submit' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "minimax-h3-max",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "resolution": "768p",
      "duration": 5,
      "aspectRatio": "16:9"
    }
  }
}'
# → { "status": "success", "response": { "id": "task_abc123" } }

# 2. Poll until response.status is COMPLETED
curl 'https://api.picsart.com/workflows/v1/models/task_abc123/result' \
  -H 'Authorization: Bearer $PICSART_API_KEY'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info minimax-h3-max  # this model's parameters
gen-ai pricing minimax-h3-max  # quote before spending credits
gen-ai generate -m minimax-h3-max \
  -p "A serene mountain lake at golden hour" \
  -d 5 \
  --ar 16:9
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `minimax/h3-max/video-generation` workflow takes MiniMax's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/minimax/h3-max/video-generation/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('minimax/h3-max/video-generation', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | yes | — | Text prompt for video generation. With reference inputs, address them by modality and order — Image 1, Image 2, Video 1, Audio 1, and so on. · max 50000 chars |
| `prompt_expansion_mode` | `string` | no | `balanced` | How much effort to spend rewriting the prompt before generation. 'balanced' returns in about a second, 'quality' spends up to ~30s on a richer prompt. · Options: `balanced`, `quality` |
| `duration` | `number` | no | `5` | Video duration in seconds · 5–15 |
| `resolution` | `string` | no | `768P` | The native generation resolution of the video, or 1080P latent refinement from a native 768P source. Case-insensitive. · Options: `480P`, `768P`, `1080P` |
| `aspect_ratio` | `string` | no | — | The aspect ratio of the generated video. Omitted, it defaults to 16:9 generating from the prompt alone and to 'adaptive' generating from references. Ignored when a frame is supplied — the output then follows that image. 'adaptive' follows the reference inputs, so it is accepted only alongside them. · Options: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| `image_url` | `string` | no | — | URL of the image to use as the first frame. When provided, the output canvas follows this image. Cannot be combined with reference inputs. |
| `end_image_url` | `string` | no | — | URL of the image to use as the last frame. It may be provided alone for end-only keyframe generation, in which case the output canvas follows this image. Cannot be combined with reference inputs. |
| `reference_image_urls` | `string[]` | no | — | URLs of subject/style reference images, referenced in the prompt as Image 1, Image 2, and so on. Reference images, videos and audio clips must add up to at most 12 files. Cannot be combined with frames. · max 9 items |
| `reference_video_urls` | `string[]` | no | — | URLs of motion/reference video clips (2-15 seconds each, combined duration at most 15 seconds), referenced in the prompt as Video 1, Video 2, and so on. Reference images, videos and audio clips must add up to at most 12 files. Cannot be combined with frames. · max 3 items |
| `reference_audio_urls` | `string[]` | no | — | URLs of reference audio clips (2-15 seconds each, combined duration at most 15 seconds), referenced in the prompt as Audio 1, Audio 2, and so on. Needs at least one reference image or video alongside it. · max 3 items |
| `seed` | `number` | no | — | Random seed. A random seed is selected when omitted. |
| `enable_safety_checker` | `boolean` | no | `true` | Run the vendor safety checker |
| `options` | `object` | no | — | GenAI options (safety checks, Picsart Drive) |
| └ `safety_checks` | `object` | no | — | Safety check settings |
| └   `enabled` | `boolean` | no | — | Whether to run content moderation. Defaults to true. |
| └ `drive` | `object` | no | — | Save result to Picsart Drive |
| └   `name` | `string` | yes | — | File name in Picsart Drive |
| └   `attributes` | `object` | no | — | Custom attributes to attach to the file |
| └   `folder` | `object` | no | — | Target folder in Picsart Drive |
| └ `inputs_transformation` | `object` | no | — | Input transformation settings |
| └   `downscale_oversized_images` | `boolean` | no | — | Whether to downscale oversized input images. Defaults to false. |

### Example request body

```json
{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'minimax/h3-max/video-generation' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('minimax/h3-max/video-generation', {
  prompt: "A serene mountain lake at golden hour, ultra detailed"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/minimax/h3-max/video-generation/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
```

#### cURL (async: submit, then poll)

```bash
# 1. Submit the job
curl -X POST 'https://api.picsart.com/workflows/minimax/h3-max/video-generation/submit' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
# → { "status": "success", "response": { "id": "wf_abc123" } }

# 2. Poll until response.status is COMPLETED
curl 'https://api.picsart.com/workflows/minimax/h3-max/video-generation/wf_abc123/result' \
  -H 'Authorization: Bearer $PICSART_API_KEY'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result.mp4",
      "mimeType": "video/mp4",
      "expandedPrompt": "…",
      "driveFile": {}
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "url": "https://cdn.picsart.com/…/result.mp4",
    "mimeType": "video/mp4",
    "expandedPrompt": "…",
    "driveFile": {}
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/minimax-h3-max
- Try it: https://picsart.com/api-platform/models/minimax-h3-max/playground
- SDK: https://picsart.com/api-platform/models/minimax-h3-max/sdk
- REST API (unified): https://picsart.com/api-platform/models/minimax-h3-max/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/minimax-h3-max/advanced
- Pricing: https://picsart.com/api-platform/models/minimax-h3-max/pricing
- This document: https://picsart.com/api-platform/models/minimax-h3-max/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction