MiniMax H3-Image API: วิธีสร้างและแก้ไขรูปภาพ

MiniMax H3-Image API สร้างและแก้ไขรูปภาพผ่าน REST endpoint สองตัว ได้แก่ POST /v1/images/generations สำหรับ text-to-image และ POST /v1/images/edits สำหรับการแก้ไขโดยใช้รูปอ้างอิง 1 ถึง 16 รูป คุณส่ง Bearer key, model ID MiniMax-H3-Image (หรือ MiniMax-H3-Image-Highspeed), prompt และขนาด แล้วจะได้รับ URL ของรูปภาพหรือข้อมูล base64 กลับมา ตัว API นี้อยู่บนแพลตฟอร์มนักพัฒนา MiniMax เดียวกับ MiniMax M3 API เอาต์พุตสามารถไปได้สูงสุดราว 16 ล้านพิกเซลโดยไม่ต้องใช้ upscaler

เนื้อหาด้านล่างนี้ประกอบด้วย: API key, ฟิลด์ที่สำคัญ, การแก้ไขรูป, ราคาพร้อมส่วนลดเปิดตัว และการทดสอบด้วย Apidog CLI ผ่าน coding agent หากยังไม่คุ้นเคยกับโมเดลนี้ เริ่มต้นจาก MiniMax H3-Image คืออะไร

MiniMax H3-Image API คืออะไร?

MiniMax H3-Image API คือ endpoint ที่ MiniMax ให้บริการสำหรับโมเดล open-weight H3-Image ซึ่งรองรับทั้ง text-to-image และการแก้ไขรูปภาพด้วยรูปอ้างอิงหลายรูปใน checkpoint เดียว บริการนี้ให้บริการที่ https://api.minimax.io รับ request แบบ JSON และใช้งานร่วมกับคำสั่ง images.generate และ images.edit ของ OpenAI SDK ได้ ดังนั้นโค้ดรูปภาพที่มีอยู่แล้วส่วนใหญ่เพียงแค่เปลี่ยน base URL และชื่อโมเดลก็ใช้ได้ทันที

นอกจากนี้ weights ยังเป็นแบบสาธารณะด้วย: Hugging Face model card ระบุ diffusion transformer ขนาด 33.1B พารามิเตอร์ภายใต้สัญญาอนุญาต MiniMax-H3-Image Community License การ self-host ต้องใช้พื้นที่ราว 69 GB สำหรับ checkpoint บวกกับ text encoder อีก 66.7 GB ดังนั้นการใช้ API จึงเป็นทางเลือกที่ใช้งานจริงที่สุดสำหรับทีมส่วนใหญ่

ฝั่งบริการโฮสต์ อ้างอิงจาก API reference ของ MiniMax ณ วันที่ 2026-11-11:

รับ MiniMax API key ของคุณ

1. ลงชื่อเข้าใช้ที่ แพลตฟอร์มนักพัฒนา MiniMax
2. เปิด Account Management แล้วไปที่ API Keys และสร้าง key
3. เติมยอดเงิน หากส่ง request โดยไม่มีเงินในบัญชีจะล้มเหลวด้วย HTTP 402 และ error code 1008 (ยอดเงินไม่เพียงพอ)
4. Export key เพื่อให้โค้ดและ agent ของคุณอ่านค่าจาก environment ไม่ใช่จากไฟล์ที่คุณ commit เข้า repo:

export MINIMAX_API_KEY="your-key-here"

ทุกครั้งที่เรียกใช้จะส่ง key ในรูปแบบ Authorization: Bearer $MINIMAX_API_KEY

Request text-to-image แรกของคุณ

คำเรียกที่เล็กที่สุดและใช้งานได้จริงต้องมี model, prompt และขนาด หรือ area tier:

curl https://api.minimax.io/v1/images/generations \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "response_format": "url"
  }'

หากใช้ OpenAI Python SDK ให้ชี้ base_url ไปที่ MiniMax และปิด retry:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
    timeout=600,
    max_retries=0,
)

result = client.images.generate(
    model="MiniMax-H3-Image",
    prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
    size="2720x1536",
    response_format="url",
)
for item in result.data:
    print(item.url)  # None for an image that failed

บรรทัด max_retries=0 สำคัญมาก endpoint นี้ไม่ใช่ idempotent: เซิร์ฟเวอร์จะทำงานเสร็จและคิดค่าใช้จ่ายของ job นั้นแม้ว่า client ของคุณจะหมดเวลา ดังนั้นการ retry อัตโนมัติจะทำให้ถูกเรียกเก็บเงินสองครั้ง ควรตั้ง timeout ไว้ที่ 600 วินาทีแทน

พารามิเตอร์ของ request ที่สำคัญ

คุณกำหนดขนาดเอาต์พุตได้สองวิธี และห้ามใช้ผสมกัน

พิกเซลแบบเจาะจง กำหนด size เป็น WIDTHxHEIGHT เช่น 4096x4096 พื้นที่รวมต้องอยู่ระหว่าง 655,360 ถึง 20,000,000 พิกเซล และอัตราส่วนภาพต้องอยู่ระหว่าง 1:3 ถึง 3:1 ห้ามส่ง aspect_ratio หรือ area ในโหมดนี้ แม้แต่ค่า auto ไม่ได้ มิฉะนั้นจะได้รับ error 400

ชั้นพื้นที่บวกอัตราส่วน ตั้ง size เป็น auto และกำหนด area (1K, 2K หรือ 4K ค่าเริ่มต้นคือ 4K) และ aspect_ratio (เป็น X:Y ใดก็ได้ตั้งแต่ 1:3 ถึง 3:1) เซิร์ฟเวอร์จะคำนวณจำนวนพิกเซลให้ เช่น 2K ที่ 16:9 จะได้ 2720 x 1536

ฟิลด์อื่น ๆ:

มีสองกฎที่มักทำให้สับสน ประการแรก หากปิด prompt enhancement คุณต้องระบุ size แบบเจาะจงหรือ aspect_ratio อย่างชัดเจน ถ้าใส่ auto จะได้รับ 400 ประการที่สอง b64_json มีการจำกัดพื้นที่เอาต์พุตรวม: 20,000,000 พิกเซลสำหรับ PNG (รูปเดียวขนาดใดก็ได้) และ 80,000,000 สำหรับ JPEG หรือ WebP (รูป 4K สี่รูปหรือรูป 2K สิบรูป) สำหรับ batch ที่ใหญ่กว่านี้ ให้ใช้ URL แทน

Model card ระบุว่า H3-Image ทำงานได้ดีที่สุดราว 16 MP: 4096x4096 (1:1), 5472x3072 (16:9) หรือ 6272x2688 (21:9)

แก้ไขรูปภาพด้วยรูปอ้างอิงได้สูงสุด 16 รูป

การแก้ไขใช้ฟิลด์ชุดเดียวกันบวกกับอาร์เรย์ images โดยอ้างอิง input ตามลำดับตำแหน่งใน prompt ("image 1", "image 2"):

import os, requests

resp = requests.post(
    "https://api.minimax.io/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
        "images": [
            {"image_url": "https://example.com/cat.jpg"},
            {"image_url": "https://example.com/dog.png"},
        ],
        "size": "auto",
        "response_format": "url",
    },
    timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])

endpoint นี้ยังรองรับ multipart/form-data ซึ่งเป็นรูปแบบที่ OpenAI SDK ใช้ส่งเมื่อคุณอัปโหลดไฟล์ผ่าน images.edit ข้อจำกัดจากเอกสาร edits reference:

• รูปภาพ 1 ถึง 16 รูป เป็นไฟล์ JPG, PNG, WebP, HEIC หรือ HEIF
• ด้านยาวแต่ละด้านอยู่ระหว่าง 128 ถึง 8,192 พิกเซล อัตราส่วนยาวต่อสั้นไม่เกิน 4:1
• ขนาด request body รวมไม่เกิน 64 MiB การใช้ base64 จะเพิ่มขนาดประมาณหนึ่งในสาม จึงควรเปลี่ยนไปใช้ public URL สำหรับ input ขนาดใหญ่

อ่าน response และจัดการ error

คำเรียกที่สำเร็จจะส่งคืนรายการ data หนึ่งรายการต่อรูปที่ request ตามลำดับ:

{
  "data": [
    {"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
    {"error": {"code": "1027", "message": "output image failed content safety check"}}
  ],
  "output_format": "jpeg",
  "usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
  "request_id": "0217..."
}

สามนิสัยนี้จะช่วยให้ integration ของคุณน่าเชื่อถือ:

1. ตรวจสอบ error ในทุกรายการ HTTP status จะเป็น 200 หากมีรูปสำเร็จอย่างน้อยหนึ่งรูป ดังนั้น 200 ไม่ได้แปลว่ารูปทั้ง n รูปกลับมาครบ หากทุกรูปล้มเหลว คุณจะได้รับ 402, 422 หรือ 500 แทน
2. ดาวน์โหลดไฟล์จาก URL ทันที MiniMax ระบุว่า URL ไม่รับประกันว่าจะพร้อมใช้งานตลอดไป จึงควรคัดลอกไฟล์ไปเก็บใน storage ของคุณเอง
3. บันทึก request_id นี่คือ trace ID ที่ทีมซัพพอร์ตจะขอ

การโดนจำกัดอัตราจะคืน 429 code 1002 หมายถึงคุณเกินจำนวนรูปต่อนาที และแต่ละ request จะถูกนับเท่ากับ n รูป ดังนั้น batch ขนาด 10 จะใช้โควตา 10 รูปในคราวเดียว

ราคาของ MiniMax H3-Image และส่วนลดเปิดตัว

การเรียกเก็บเงินคิดเป็นราย token และคุณจ่ายเฉพาะรูปที่สร้างสำเร็จเท่านั้น จากหน้าราคาของ MiniMax อ่านเมื่อ 2026-11-11:

MiniMax ยังเผยแพร่ตัวอย่างต้นทุนต่อรูปสำหรับโมเดล standard:

Highspeed มีต้นทุนต่อรูปสูงกว่าประมาณ 1.6 ถึง 2 เท่า ($0.13001 สำหรับ 4K, $0.06501 เมื่อลดราคา) ความยาวของ prompt ส่งผลต่อค่าใช้จ่ายฝั่ง input ดังนั้นให้มองตัวเลขเหล่านี้เป็นเพียงค่าประมาณการ

ข้อเสนอเปิดตัว: จนถึงวันที่ 17 พฤศจิกายน 2026 เวลา 16:00 UTC MiniMax ลดราคาคำ request รวม 50% สำหรับทั้งสองโมเดล เมื่อรูปที่ส่งมอบมีอย่างน้อย 16,600,000 พิกเซล รูปขนาด 4096x4096 (16,777,216 พิกเซล) มีสิทธิ์ได้รับ ส่วนรูป 2K ไม่ได้ กำลังมองหาวิธีใช้ฟรีอยู่ใช่ไหม? ดูวิธีใช้ MiniMax H3-Image ฟรี

ให้ coding agent ของคุณทดสอบด้วย Apidog CLI

Image API มักล้มเหลวอย่างเงียบ ๆ: ได้ 200 แต่รูปหายไปครึ่งหนึ่ง หรือกฎเรื่องขนาดที่คุณลืม ให้ coding agent ของคุณ (Claude Code, Codex, Cursor) สร้างชุดทดสอบที่ทำซ้ำได้ด้วย Apidog CLI แทนการตรวจ response ด้วยมือ

ติดตั้งครั้งเดียว:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

จากนั้นสั่ง agent ของคุณด้วย prompt เดียว:

In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.

Agent จะอ่าน schema ของ payload แต่ละตัว ตรวจสอบ JSON สร้าง resource และรัน test case:

apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json

--env-var ส่ง key ของคุณตอนรัน จึงไม่มีทางไปอยู่ในไฟล์ที่บันทึกไว้ reporter แบบ cli จะแสดง assertion แต่ละข้อว่าผ่านหรือไม่ผ่าน ส่วน json จะเขียนรายงานที่ agent ของคุณอ่านกลับได้ ให้ทดสอบที่ 1K เพราะทุกการรันคือการสร้างรูปจริงที่มีค่าใช้จ่าย บรรทัดเดียวกันนี้รันใน CI ได้ด้วย -r junit (ดูคู่มือ Apidog CLI CI/CD และ Apidog CLI ใน Claude Code) แพลน Free ของ Apidog รองรับผู้ใช้ได้ถึง 4 คน

Standard หรือ Highspeed: ควรใช้ model ID ตัวไหน?

ทั้งสอง ID รับพารามิเตอร์เหมือนกัน ดังนั้นการสลับก็แค่เปลี่ยน string หนึ่งตัว ใช้ MiniMax-H3-Image สำหรับผลงานสุดท้ายและ batch ที่สำคัญเรื่องต้นทุน และใช้ MiniMax-H3-Image-Highspeed สำหรับ preview แบบ interactive ที่ความเร็วสำคัญกว่าราคา API reference ไม่ได้ระบุตัวเลข latency จึงควรจับเวลาด้วย prompt ของคุณเอง กำลังประเมินทางเลือกอื่นอยู่? อ่าน MiniMax H3-Image vs Nano Banana 2.1, คู่มือ Nano Banana 2.1 API หรือ คู่มือ GPT Image 2.6 API

คำถามที่พบบ่อย

Model ID ของ MiniMax H3-Image คืออะไร? ใช้ MiniMax-H3-Image สำหรับโมเดล standard หรือ MiniMax-H3-Image-Highspeed สำหรับเวอร์ชันที่เร็วกว่าแต่แพงกว่า ทั้งสองใช้ได้กับ /v1/images/generations และ /v1/images/edits ด้วยพารามิเตอร์ชุดเดียวกัน

MiniMax H3-Image API ใช้กับ OpenAI SDK ได้ไหม? ได้ ตั้ง base_url="https://api.minimax.io/v1" แล้วเรียก images.generate หรือ images.edit อย่าลืมตั้ง max_retries=0 เพราะการ retry จะสร้างการสร้างรูปใหม่ที่ถูกคิดเงิน

ใช้รูปอ้างอิงสำหรับแก้ไขได้กี่รูป? 1 ถึง 16 รูปต่อ request แต่ละรูปมีด้านละ 128 ถึง 8,192 พิกเซล และ request body ทั้งหมดต้องไม่เกิน 64 MiB

รูปหนึ่งของ MiniMax H3-Image ราคาเท่าไร? จากตัวอย่างของ MiniMax การเรียก text-to-image โมเดล standard อยู่ที่ประมาณ $0.022 สำหรับ 1K และ $0.069 สำหรับ 4K โดย 4K จะลดเหลือครึ่งหนึ่งเหลือประมาณ $0.034 จนถึงวันที่ 17 พฤศจิกายน 2026 เวลา 16:00 UTC

ทำไมได้ 200 แต่ได้รูปน้อยกว่าที่ขอ? ความสำเร็จบางส่วนจะคืน 200 รายการที่ล้มเหลว รวมถึงรายการที่ถูกบล็อกโดยการตรวจความปลอดภัย จะมี object error แทนที่จะเป็น url และคุณจะไม่ถูกคิดค่าใช้จ่ายสำหรับรูปเหล่านั้น