Minimax H3

All modes, complete request fields and examples for this model.

ENDPOINT

POSThttps://platform-backend.topview.ai/api/v1/models/minimax/minimax-h3/text-to-video/predictions

Mode

Authentication

Authenticate with your Platform API key in the Authorization header.

Authorization: Bearer YOUR_PLATFORM_KEYView API Keys

Your key needs models:generate and requests:read permissions. Only the following parameters are supported. Unsupported fields return 400 without a charge.

Submit Task

Submit model parameters directly; no estimate request is required. Save data.id to retrieve status, results and the final charge.

# Set TOPVIEW_API_PLATFORM_KEY once. Preserve REQUEST_KEY and input for uncertain retries.
# For a NEW task only, unset REQUEST_KEY first. Save data.id to resume GET only.
: "${TOPVIEW_API_PLATFORM_KEY:?Set TOPVIEW_API_PLATFORM_KEY first}"
export REQUEST_KEY="${REQUEST_KEY:-$(uuidgen)}"
curl --fail-with-body 'https://platform-backend.topview.ai/api/v1/models/minimax/minimax-h3/text-to-video/predictions' \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "content": [
    {
      "type": "text",
      "text": "A blue paper boat floating on a calm pond"
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}'

Use a unique Idempotency-Key per task. Retry an uncertain submission with the same key and request. Python / JavaScript save input and idempotency key before submission in REQUEST_STATE (default .topview-request.json); keep this file private. Restart with the same file to recover, or set TASK_ID for GET-only recovery. Use a new state path for a new task. Polling retries network errors, 429 and 5xx with bounded backoff and Retry-After; after the retry limit or 30 minutes, resume the saved task ID.

Result Guide

Submit asynchronously and poll for results.

Save data.id after submission. HTTP 200 does not mean generation has completed.
Call GET with the original creating API key, requests:read and the corresponding mode permission. A new or rotated key cannot read the old key’s tasks. View Playground tasks in signed-in web history; authorized workspace members can also use web history after the original key expires or is revoked. Poll every 2–5 seconds and back off for long tasks or 429 / 5xx responses.
Keep polling created / processing tasks. On completed, read data.outputs. On failed, read data.error and stop polling.
payment_required means settlement needs more funds. amount_due_usd is the actual cost, additional_charge_usd is the amount above the original hold, and shortfall_usd is the eligible balance shortage. Top up the same workspace; settlement retries automatically without resubmitting. Estimates are not a cap: sufficient balance is automatically charged for the difference.
Read charged_usd and billing_state for settlement. Save results promptly because media URLs may expire. After a timeout, query the original task rather than creating a duplicate.

GEThttps://platform-backend.topview.ai/api/v1/predictions/REQUEST_ID

Replace REQUEST_ID with data.id. Poll data.status until completed or failed; successful results are in data.outputs.

curl --fail-with-body 'https://platform-backend.topview.ai/api/v1/predictions/REQUEST_ID' \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "TASK_ID",
    "status": "completed",
    "outputs": [
      "https://example.com/generated-result"
    ],
    "charged_usd": "0.040000000000",
    "billing_state": "CAPTURED",
    "error": ""
  }
}

createdprocessingpayment_requiredcompletedfailed

data.charged_usd is the actual task cost in USD, returned as an exact decimal string. data.billing_state: RESERVED holds funds, CAPTURED settles the charge, and RELEASED returns the hold.

Schema

Request and response schemas for the selected mode.

Submit requests using official field names. The API path selects the model; no model identifier is needed in the request body. Required fields, defaults and mode-specific constraints are defined below.

MiniMax H3 V2 supports aigc_watermark. It does not expose legacy prompt_optimizer or seed. extra.prompt_expansion_mode belongs to H3 Max, not H3. Text-only input requires a non-adaptive ratio; reference input may omit ratio.

Input schema

Common parameters match the Playground form. Use the API field path in request JSON; descriptions explain nested fields and media roles. — means no declared default, not null or zero.

Parameter / API path	Required	Type	Default	Options / limits	Description
`prompt`API: `content[].text`	Yes	`string`	—	min length 1; max length 10000	Describe the desired content. content item: type=text.
`aspect_ratio`API: `ratio`	No	`string`	Form: "16:9"; API: —	"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9"	Output aspect ratio. Required and non-adaptive for text-only requests; optional for reference input; frame input uses adaptive upstream.
`resolution`	No	`string`	"768P"	"768P", "2K"	Output resolution.
`duration`	No	`integer`	Form: 5; API: —	min 4; max 15	Output duration in seconds. 4–15 seconds; default 5 in Platform.

Advanced parameters and complete request structure

Parameter / API path	Required	Type	Default	Options / limits	Description
`content`	No	`object[]`	—	—	Official multimodal content, forwarded without renaming.
`content[].type`	No	`string`	—	"text", "image_url", "video_url", "audio_url"	Content or media item type.
`content[].text`	No	`string`	—	—	Text to synthesize or process.
`content[].role`	No	`string`	—	—	Media role within the generation request.
`content[].image_url`	No	`object`	—	—	Image URL object.
`content[].image_url.url`	No	`string`	—	—	Official: 256–5760 px per side; width/height 0.4–2.5; at most 30 MB. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created.
`content[].video_url`	No	`object`	—	—	Video URL object.
`content[].video_url.url`	No	`string`	—	—	Public media URL.
`content[].audio_url`	No	`object`	—	—	Audio URL object.
`content[].audio_url.url`	No	`string`	—	—	Public media URL.
`aigc_watermark`	No	`boolean`	false	true, false	Whether to add an AI-generated-content watermark.

Raw input JSON Schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "array",
      "description": "Official multimodal content, forwarded without renaming.",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image_url",
              "video_url",
              "audio_url"
            ]
          },
          "text": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "image_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Official: 256–5760 px per side; width/height 0.4–2.5; at most 30 MB. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created."
              }
            }
          },
          "video_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            }
          },
          "audio_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "duration": {
      "type": "integer",
      "description": "4–15 seconds; default 5 in Platform."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "768P",
        "2K"
      ],
      "default": "768P"
    },
    "ratio": {
      "type": "string",
      "description": "Required and non-adaptive for text-only requests; optional for reference input; frame input uses adaptive upstream."
    },
    "aigc_watermark": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false,
  "description": "Native request fields. The model route supplies model when omitted. Platform authentication, idempotency and asynchronous prediction responses remain unchanged.",
  "x-supplier-notes": [
    {
      "supplier": "minimax",
      "unsupported": [
        "seed",
        "prompt_optimizer",
        "extra.prompt_expansion_mode"
      ],
      "reason": "The H3 V2 contract does not expose seed or the legacy prompt_optimizer; prompt_expansion_mode is exclusive to H3 Max, which is outside this model."
    }
  ]
}

Output schema

Task query response. Generation results are inside data. Nested field presence depends on the parent being returned.

Parameter / API path	Required	Type	Default	Options / limits	Description
`code`	Yes	`integer`	—	—	HTTP API envelope code. Inspect data.status for the task outcome.
`message`	Yes	`string`	—	—	API response message.
`data`	Yes	`object`	—	—	Prediction task details.
`data.id`	Yes	`string`	—	—	Platform task ID. Persist it before polling.
`data.created_at`	Yes	`string`	—	date-time	Task creation timestamp.
`data.code`	Yes	`integer`	—	—	0 for normal tasks; 402 when payment is required; 1403 for a failed task.
`data.execution_state`	Yes	`string`	—	—	Execution state; inspect status and billing_state before treating a task as settled.
`data.status`	Yes	`string`	—	"created", "processing", "payment_required", "completed", "failed"	Current task status.
`data.outputs`	Yes	`string[]`	—	—	Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix.
`data.amount_due_usd`	No	`string`	—	—	Full actual cost in USD, present when status is payment_required.
`data.additional_charge_usd`	No	`string`	—	—	Actual cost minus the original reservation; present when payment is required.
`data.shortfall_usd`	No	`string`	—	—	Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed.
`data.charged_usd`	Yes	`string`	—	—	Actual USD charge as an exact decimal string, not the reserved amount.
`data.billing_state`	Yes	`string`	—	"RESERVED", "CAPTURED", "RELEASED"	RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.
`data.error`	Yes	`string`	—	—	Failure or payment-required description, otherwise an empty string.
`data.urls`	Yes	`object`	—	—	Task-related API URLs.
`data.urls.get`	Yes	`string`	—	uri	Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission.
`data.last_frame_url`	No	`string`	—	uri	Last-frame image URL when requested and returned, available only after settlement.

Raw output JSON Schema

{
  "type": "object",
  "required": [
    "code",
    "message",
    "data"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "HTTP API envelope code. Inspect data.status for the task outcome."
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "id",
        "created_at",
        "code",
        "execution_state",
        "status",
        "outputs",
        "charged_usd",
        "billing_state",
        "error",
        "urls"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Platform task ID. Persist it before polling."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "code": {
          "type": "integer",
          "description": "0 for normal tasks; 402 when payment is required; 1403 for a failed task."
        },
        "execution_state": {
          "type": "string",
          "description": "Execution state; inspect status and billing_state before treating a task as settled."
        },
        "status": {
          "type": "string",
          "enum": [
            "created",
            "processing",
            "payment_required",
            "completed",
            "failed"
          ]
        },
        "outputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix."
        },
        "amount_due_usd": {
          "type": "string",
          "description": "Full actual cost in USD, present when status is payment_required."
        },
        "additional_charge_usd": {
          "type": "string",
          "description": "Actual cost minus the original reservation; present when payment is required."
        },
        "shortfall_usd": {
          "type": "string",
          "description": "Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed."
        },
        "charged_usd": {
          "type": "string",
          "description": "Actual USD charge as an exact decimal string, not the reserved amount.",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "example": "0.040000000000"
        },
        "billing_state": {
          "type": "string",
          "description": "RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.",
          "enum": [
            "RESERVED",
            "CAPTURED",
            "RELEASED"
          ]
        },
        "error": {
          "type": "string",
          "description": "Failure or payment-required description, otherwise an empty string."
        },
        "urls": {
          "type": "object",
          "required": [
            "get"
          ],
          "properties": {
            "get": {
              "type": "string",
              "format": "uri",
              "description": "Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission."
            }
          }
        },
        "last_frame_url": {
          "type": "string",
          "format": "uri",
          "description": "Last-frame image URL when requested and returned, available only after settlement."
        }
      }
    }
  }
}

Errors

HTTP	Meaning & recovery
`400`	Invalid or unsupported input. Check the schema.
`401`	Missing or invalid credentials. Check your API key.
`403`	Insufficient key permissions or model access.
`404`	Resource missing or inaccessible to this workspace.
`409`	Idempotency or version conflict. Check the original request.
`429`	Concurrency or rate limit reached. Wait and retry with backoff.
`5xx`	Temporary server error. Back off queries; keep the original idempotency key for uncertain submissions.

HTTP success does not guarantee generation success. Inspect data.status, data.error and billing_state.

Documentation