Skip to main content

MiniMax H3 Customer Callbacks

All three creation endpoints accept an optional callback_url for terminal task notifications sent by the platform. Omit it when polling only. The platform stores and notifies your URL instead of passing it directly to MiniMax. Administrators maintain the platform-to-MiniMax callback configuration.

Step 1: Implement URL verification​

Before creating a task, the platform sends a POST to callback_url:

{"challenge":"verification_value"}

Within 3 seconds, return HTTP 2xx and echo the same challenge. A JSON response is supported:

{"challenge":"verification_value"}

Returning the challenge as plain response text is also supported. Do not redirect to a login page, return HTML, or change the value. The platform does not follow redirects. Use an HTTP(S) URL reachable from the platform network and permitted by its URL security policy.

Step 2: Set the URL when creating a task​

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "ratio": "16:9",
  "content": [{"type": "text", "text": "A kitten stretches in the sunshine"}],
  "callback_url": "https://example.com/webhooks/minimax-h3"
}

Replace the URL with your actual service. Failed verification rejects task creation. Omit callback_url when using polling.

Step 3: Receive terminal notifications​

The platform sends terminal notifications only, without queued/running updates. The body matches the query response. task.id is the platform task ID. Video output is in task.content.url; Context-IR output is in task.content.prompt. Upstream usage is excluded.

{
  "task": {
    "id": "task_platform_example",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "generation",
    "modality": "video",
    "content": {"url": "https://example.com/generated-video.mp4"},
    "created_at": 1792540800
  }
}

Respond with HTTP 2xx within 3 seconds. Save the notification first, then handle slow work such as downloads asynchronously.

Delivery and verification limits​

  • Terminal notification delivery currently uses a single send attempt. Automatic retries and at-least-once delivery are not guaranteed; always use the query API as a fallback.
  • Process notifications idempotently by task.id so duplicates cannot repeat business actions.
  • The challenge checks URL responsiveness; it is not a notification signature. Customer notifications currently have no dedicated signature field or model API key authorization header. Use an unguessable callback URL and verify task ownership, status, and results through an authenticated platform query before critical business actions.
  • Do not put model API keys in callback URLs, public logs, or browser code. The internal /api/callback/minimax-h3/... endpoint is not a customer business API to call directly.