MiniMax H3-Image API ile Görsel Oluşturma ve Düzenleme

MiniMax H3-Image API, görüntü oluşturma ve düzenlemeyi iki REST uç noktası üzerinden gerçekleştirir: metinden görüntüye için POST /v1/images/generations ve 1 ila 16 referans görüntüyle düzenleme için POST /v1/images/edits. Bir Bearer anahtarı, model kimliği MiniMax-H3-Image (veya MiniMax-H3-Image-Highspeed), bir prompt ve bir boyut gönderirsiniz; karşılığında görüntü URL'leri veya base64 verisi alırsınız. API, MiniMax M3 API'nin de üzerinde bulunduğu aynı MiniMax geliştirici platformunda çalışır. Çıktı, upscaler olmadan yaklaşık 16 megapikseline kadar çıkabilir.

Aşağıda: anahtar, önemli alanlar, düzenleme, lansman indirimli fiyatlandırma ve Apidog CLI ile bir ajan tarafından yürütülen test yer alıyor. Modele yeni mi geldiğiniz? Önce MiniMax H3-Image nedir yazımıza göz atın.

MiniMax H3-Image API nedir?

MiniMax H3-Image API, MiniMax'in açık ağırlıklı H3-Image modeli için barındırılan uç noktasıdır; tek bir kontrol noktasında hem metinden görüntüye hem de çoklu referanslı görüntü düzenlemeyi destekler. API, https://api.minimax.io adresinde hizmet verir, JSON isteklerini kabul eder ve OpenAI SDK'sının images.generate ve images.edit çağrılarıyla uyumludur; dolayısıyla mevcut görüntü kodlarının çoğu yalnızca yeni bir base URL ve model adı gerektirir.

Model ağırlıkları da herkese açıktır: Hugging Face model kartı, MiniMax-H3-Image Community License altında 33,1 milyar parametreli bir diffusion transformer listeler. Kendi sunucunuzda barındırmak, kontrol noktası için yaklaşık 69 GB ve 66,7 GB'lık bir metin kodlayıcı için ek alan gerektirir; bu nedenle çoğu ekip için API en pratik yoldur.

MiniMax'in 2026-11-11 tarihli API referansına göre barındırılan taraf:

MiniMax API anahtarınızı alın

1. MiniMax geliştirici platformunda oturum açın.
2. Hesap Yönetimi'ni (Account Management), ardından API Keys bölümünü açın ve bir anahtar oluşturun.
3. Bakiye ekleyin. Bakiyesi olmayan bir istek, HTTP 402 ve 1008 hata koduyla (yetersiz bakiye) başarısız olur.
4. Anahtarı dışa aktarın; böylece kodunuz ve ajanınız onu ortam değişkeninden okur, asla commit ettiğiniz bir dosyadan değil:

export MINIMAX_API_KEY="your-key-here"

Her çağrı, anahtarı Authorization: Bearer $MINIMAX_API_KEY olarak gönderir.

İlk metinden görüntüye isteğiniz

En küçük işlevsel çağrı, model, prompt ve bir boyut ya da bir alan katmanı (area tier) gerektirir:

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'sı ile base_url değerini MiniMax'e yönlendirin ve yeniden denemeleri kapatın:

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 satırı önemlidir. Uç nokta idempotent değildir: istemciniz zaman aşımına uğrasa bile sunucu işi tamamlar ve ücretlendirir; dolayısıyla otomatik bir yeniden deneme çift faturalandırmaya yol açar. Bunun yerine 600 saniyelik bir zaman aşımı ayarlayın.

Önemli istek parametreleri

Çıktı boyutunu iki yoldan biriyle kontrol edersiniz ve ikisini karıştıramazsınız.

Tam pikseller. size değerini GENİŞLİKxYÜKSEKLİK olarak ayarlayın, örneğin 4096x4096. Toplam alan 655.360 ile 20.000.000 piksel arasında ve en-boy oranı 1:3 ile 3:1 arasında olmalıdır. Bu modda aspect_ratio veya area göndermeyin, auto olarak bile; aksi halde 400 hatası alırsınız.

Katman artı oran. size değerini auto bırakın ve area (1K, 2K veya 4K, varsayılan 4K) ile aspect_ratio (1:3 ile 3:1 arası herhangi bir X:Y) değerlerini ayarlayın. Sunucu pikselleri hesaplar; 16:9 oranındaki 2K, 2720 x 1536 döndürür.

Diğer alanlar:

İki kural insanları yakalar. Birincisi, prompt geliştirmeyi kapatırsanız tam bir size ya da açık bir aspect_ratio vermelisiniz; auto 400 hatası döndürür. İkincisi, b64_json toplam çıktı alanını sınırlar: PNG için 20.000.000 piksel (herhangi bir boyutta tek görüntü) ve JPEG veya WebP için 80.000.000 piksel (dört 4K görüntü veya on 2K görüntü). Daha büyük toplu işler için URL'leri kullanın.

Model kartına göre H3-Image, yaklaşık 16 MP civarında en iyi şekilde çalışır: 4096x4096 (1:1), 5472x3072 (16:9) veya 6272x2688 (21:9).

16 referansa kadar görüntüyle düzenleme

Düzenleme, aynı alanları artı bir images dizisi kullanır. Girdilere prompt içindeki konumlarıyla atıfta bulunun (“1. görüntü”, “2. görüntü”):

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"])

Uç nokta ayrıca multipart/form-data kabul eder; OpenAI SDK'sının images.edit çağrısı, dosya yüklerken bunu kullanır. edits referansından sınırlar:

• JPG, PNG, WebP, HEIC veya HEIF biçimlerinde 1 ila 16 görüntü
• Her kenar 128 ile 8.192 piksel arasında, uzun-kısa oranı en fazla 4:1
• Toplam istek gövdesi 64 MiB'ye kadar; base64 yaklaşık üçte bir ekler, bu yüzden büyük girdiler için herkese açık URL'lere geçin

Yanıtı okuma ve hataları işleme

Başarılı bir çağrı, istenen her görüntü için sırayla bir data öğesi döndürür:

{
  "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..."
}

Üç alışkanlık entegrasyonunuzu sağlam tutar:

1. Her öğeyi error açısından kontrol edin. En az bir görüntü başarılı olursa HTTP durumu 200'dür; yani 200, n görüntünün tamamının geldiği anlamına gelmez. Tüm görüntüler başarısız olursa bunun yerine 402, 422 veya 500 alırsınız.
2. URL'leri hemen indirin. MiniMax, URL'nin erişilebilir kalacağının garanti edilmediğini belirtir; dolayısıyla dosyayı kendi depolama alanınıza kopyalayın.
3. request_id değerini kaydedin. Destek ekibinin istediği izleme kimliği budur.

Hız limitleri 429 döndürür. 1002 kodu, dakikadaki görüntü limitini aştığınız anlamına gelir ve her istek n görüntü olarak sayılır; dolayısıyla 10'luk bir toplu iş, kotanızdan aynı anda 10 birim kullanır.

MiniMax H3-Image fiyatlandırması ve lansman indirimi

Faturalandırma token başınadır ve yalnızca başarılı olan görüntüler için ödeme yaparsınız. 2026-11-11 tarihinde okunan MiniMax'in fiyatlandırma sayfasından:

MiniMax ayrıca standart model için görüntü başına örnek maliyetler yayınlıyor:

Highspeed, görüntü başına kabaca 1,6 ila 2 kat daha pahalıdır (4K için $0.13001, indirimli $0.06501). Prompt uzunluğu girdi tarafını etkiler, bu yüzden bunları tahmini değerler olarak görün.

Lansman kampanyası: 17 Kasım 2026, 16:00 UTC'ye kadar, teslim edilen görüntü en az 16.600.000 piksel içerdiğinde MiniMax her iki model için de toplam istek maliyetinde %50 indirim uygular. 4096x4096 bir görüntü (16.777.216 piksel) hak kazanır; 2K bir görüntü kazanmaz. Bunun yerine $0 maliyetli yollar mı arıyorsunuz? MiniMax H3-Image'ı ücretsiz nasıl kullanacağınızı inceleyin.

Kodlama ajanınızın Apidog CLI ile test etmesine izin verin

Görüntü API'leri sessizce başarısız olur: görüntülerin yarısının eksik olduğu bir 200 yanıtı, unuttuğunuz bir boyut kuralı. Yanıtları elle kontrol etmek yerine, kodlama ajanınızın (Claude Code, Codex, Cursor) Apidog CLI ile tekrarlanabilir bir test oluşturmasına izin verin.

Tek seferde kurulum:

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

Ardından ajanınıza tek bir prompt verin:

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.

Ajan her payload şemasını okur, JSON'unu doğrular, kaynakları oluşturur ve test senaryosunu çalıştırır:

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, anahtarınızı çalışma anında iletir; böylece anahtar asla kaydedilmiş bir dosyaya yazılmaz. cli raporlayıcısı her doğrulamayı geçti/kaldı olarak yazdırır; json ise ajanınızın geri okuduğu bir rapor dosyası oluşturur. Testi 1K boyutunda tutun: her çalıştırma gerçek, ücretlendirilen bir oluşturmadır. Aynı satır CI'da -r junit ile çalışır (Apidog CLI CI/CD rehberine ve Claude Code'da Apidog CLI yazısına bakın). Apidog'un Ücretsiz planı 4 kullanıcıya kadar kapsar.

Standart mı, Highspeed mı: hangi model kimliği?

Her iki kimlik de aynı parametreleri alır; dolayısıyla geçiş tek bir dize değişikliğidir. Nihai varlıklar ve maliyet hassasiyeti olan toplu işler için MiniMax-H3-Image, gecikmenin fiyattan önemli olduğu etkileşimli önizlemeler için MiniMax-H3-Image-Highspeed kullanın. API referansı bir gecikme değeri vermez, bu yüzden kendi promptlarınızla süreyi ölçün. Alternatifleri mi değerlendiriyorsunuz? MiniMax H3-Image vs Nano Banana 2.1, Nano Banana 2.1 API rehberi veya GPT Image 2.6 API rehberi yazılarını okuyun.

SSS

MiniMax H3-Image model kimliği nedir? Standart model için MiniMax-H3-Image, daha hızlı ve daha pahalı sürüm için MiniMax-H3-Image-Highspeed kullanın. Her ikisi de aynı parametrelerle /v1/images/generations ve /v1/images/edits üzerinde çalışır.

MiniMax H3-Image API, OpenAI SDK ile çalışıyor mu? Evet. base_url="https://api.minimax.io/v1" ayarlayın ve images.generate veya images.edit çağırın. max_retries=0 ayarlayın, çünkü yeniden denemeler yeni ücretlendirilen oluşturmalar başlatır.

Düzenleme için kaç referans görüntü kullanabilirim? İstek başına 1 ila 16 arası; her biri kenar başına 128 ile 8.192 piksel arasında ve tüm istek gövdesi 64 MiB altında.

Bir MiniMax H3-Image görüntüsü ne kadar tutar? MiniMax'in örneklerine göre standart bir metinden görüntüye çağrısı 1K için yaklaşık $0,022 ve 4K için yaklaşık $0,069; 4K, 17 Kasım 2026, 16:00 UTC'ye kadar yarıya düşerek yaklaşık $0,034 oluyor.

Neden 200 aldım ama istediğimden daha az görüntü geldi? Kısmi başarı 200 döndürür. Başarısız öğeler (güvenlik kontrolüne takılanlar dahil) bir url yerine bir error nesnesi taşır ve bu öğeler için ücretlendirilmezsiniz.