MiniMax H3 Image

Use minimax-h3-image (Standard) or minimax-h3-image-highspeed for text-to-image and reference-image editing. Use minimax-h3-image-context-ir for independent prompt enhancement, which returns text without creating images.

Pricing

Rates are in CNY per million tokens. Your account pricing multiplier applies.

Image billing uses the returned text-input, image-input, and image-output token counts. These counts already cover only successful images and include built-in prompt enhancement; do not multiply them by n again. Standalone enhancement bills only usage.input_tokens, which already includes its equivalent enhancement costs.

Limited 4K offer

For requests dispatched before November 18, 2026, 00:00 Beijing time (exclusive), the whole request receives 50% off if every successful image has at least 16,600,000 pixels, based on actual returned dimensions. Dispatch time fixes the time eligibility. Mixed qualifying/nonqualifying sizes or missing dimensions require billing review. Standalone prompt enhancement is excluded. The regular rates apply after the cutoff.

Generate or edit images

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "input": {
      "prompt": "A quiet reading room in soft morning light",
      "area": "2K",
      "aspect_ratio": "16:9",
      "n": 2,
      "nsfw_checker": true
    }
  }'

Add input.image_urls with 1–16 reference URLs for editing. Omit it for text-to-image. callback_url is optional at the top level.

{
  "model": "minimax-h3-image-highspeed",
  "input": {
    "prompt": "Preserve the product and replace the background with a bright studio",
    "image_urls": ["https://your-storage.example/product.png"],
    "size": "2048x2048",
    "n": 1,
    "output_format": "png"
  }
}

Input parameters

A custom size must not be combined with area or aspect_ratio, including auto. The Playground removes those controls when custom dimensions are entered. Reference image formats accepted by the image API are JPG/JPEG/PNG/WebP/HEIC/HEIF, up to 64 MiB each, 128–8192 pixels on each side, and long/short-side ratio at most 4. The Playground uploader currently accepts JPEG/PNG/WebP up to 10 MB per image. Platform requests use URL references and URL output, rather than embedding large image bodies.

Standalone prompt enhancement

curl -X POST https://api.aivideoapi.ai/v1/images/prompt-enhancements \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-image-context-ir","input":{"prompt":"A sunlit reading room"}}'

Supports prompt, optional image_urls, nsfw_checker (default true, subject to the same account permissions), and the same size controls. Size controls influence enhancement with reference images; prompt-only enhancement chooses its own composition. It supports the Standard model only and returns an async task ID. Completed output contains revised_prompt and, when provided by the enhancement, aspect_ratio.

For two-step text-to-image, submit revised_prompt as the new prompt with disable_prompt_enhanced: true and an explicit size or aspect ratio. Editing always enhances again and bills that enhancement even if you supply a previously enhanced prompt.

Task results and recovery

Task creation response

Image generation, image editing, and standalone prompt enhancement return a task ID after submission:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "b89c7408-2e66-4cb8-9c39-9f4699a6834f"
  }
}

Query the task using that ID:

curl https://api.aivideoapi.ai/v1/tasks/b89c7408-2e66-4cb8-9c39-9f4699a6834f \
  -H "Authorization: Bearer sk-your-api-key"

The following task-query responses use illustrative URLs, prompts, usage, and credit amounts. Timestamps are in seconds.

Completed image generation or editing

{
  "id": "b89c7408-2e66-4cb8-9c39-9f4699a6834f",
  "status": "completed",
  "model": "minimax-h3-image",
  "credits_consumed": 8.38,
  "created_at": 1794362400,
  "settlement_status": "settled",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "completed_at": 1794362460,
  "output": {
    "urls": [
      "https://your-storage.example/reading-room-1.jpeg",
      "https://your-storage.example/reading-room-2.jpeg"
    ],
    "images": [
      {
        "image_index": 0,
        "url": "https://your-storage.example/reading-room-1.jpeg",
        "size": "2736x1536",
        "revised_prompt": "Warm morning sunlight streams through tall windows, illuminating wooden desks and neatly arranged bookshelves in a quiet reading room."
      },
      {
        "image_index": 1,
        "url": "https://your-storage.example/reading-room-2.jpeg",
        "size": "2736x1536",
        "revised_prompt": "Warm morning sunlight streams through tall windows, illuminating wooden desks and neatly arranged bookshelves in a quiet reading room."
      }
    ],
    "requested_count": 2,
    "succeeded_count": 2
  },
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 8000,
    "total_tokens": 9000,
    "generated_images": 2,
    "text_input_tokens": 1000,
    "image_input_tokens": 0,
    "image_output_tokens": 8000
  }
}

Standard, Highspeed, and image editing share this result structure. image_index is zero-based. Partial success also returns completed: urls and images contain only successful images with their original indices. For example, if only the second of two requested images succeeds, requested_count is 2, succeeded_count and usage.generated_images are 1, and the only image has image_index: 1. usage contains aggregate usage for successful images; credits_consumed is the final charge with at most two decimal places.

Completed standalone prompt enhancement

{
  "id": "a510fa06-ddd5-474e-9395-809208c754d6",
  "status": "completed",
  "model": "minimax-h3-image-context-ir",
  "credits_consumed": 2.04,
  "created_at": 1794362400,
  "settlement_status": "settled",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "completed_at": 1794362415,
  "output": {
    "revised_prompt": "A quiet reading room with soft sunlight streaming through tall windows onto wooden desks, neatly arranged bookshelves, warm natural tones, and a wide composition.",
    "aspect_ratio": "16:9"
  },
  "usage": {
    "input_tokens": 3489,
    "total_tokens": 3489
  }
}

Standalone enhancement does not return image URLs. aspect_ratio is present only when supplied by the enhancement result.

Task awaiting review

{
  "id": "b89c7408-2e66-4cb8-9c39-9f4699a6834f",
  "status": "processing",
  "model": "minimax-h3-image",
  "credits_consumed": 0,
  "created_at": 1794362400,
  "settlement_status": "reconciliation_required",
  "billing_mode": "usage",
  "charge_timing": "completion",
  "progress": null
}

The final bill is not yet available: credits_consumed: 0 does not mean the request is free. This query response does not yet contain output or usage.

Requests may run for up to 600 seconds. Submitted tasks cannot be cancelled. A timed-out or disconnected request may still have generated images, so the platform never automatically resubmits generation. Saved results can be delivered or settled again without regenerating them. Missing usage, conflicting results, or uncertain discount eligibility remain processing with settlement_status: "reconciliation_required". No final charge is inferred or displayed as free. Completed tasks cannot enter failure-refund handling.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

• The key does not start with sk-
• The key has been disabled or deleted
• The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

• The input contains sensitive or prohibited content
• The provider is temporarily unavailable
• The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.