واجهة برمجة تطبيقات MiniMax H3-Image: كيفية إنشاء الصور وتعديلها

تولّد واجهة برمجة التطبيقات MiniMax H3-Image الصور وتحرّرها عبر نقطتي نهاية REST: POST /v1/images/generations للتحويل من نص إلى صورة، وPOST /v1/images/edits للتحرير باستخدام ما بين صورة مرجعية واحدة و16 صورة. ترسل مفتاح Bearer ومعرّف النموذج MiniMax-H3-Image (أو MiniMax-H3-Image-Highspeed) ونصًا توجيهيًا (prompt) وحجمًا، فتحصل في المقابل على روابط صور أو بيانات base64. تعمل الواجهة على منصة MiniMax المطوِّرين نفسها التي تقدّم واجهة MiniMax M3 API. ويصل الناتج إلى نحو 16 ميجابكسل دون الحاجة إلى أداة رفع دقة.

في ما يلي: المفتاح، الحقول المهمة، التحرير، الأسعار مع خصم الإطلاق، واختبار ينفّذه وكيل ذكاء اصطناعي باستخدام Apidog CLI. هل هي تجربتك الأولى مع النموذج؟ ابدأ بـالتعرف على ما هو MiniMax H3-Image.

ما هي واجهة MiniMax H3-Image API؟

واجهة MiniMax H3-Image API هي نقطة النهاية المستضافة من MiniMax لنموذجها مفتوح الأوزان H3-Image، الذي يتولى التحويل من نص إلى صورة وتحرير الصور بمراجع متعددة في نقطة تفتيش واحدة. تُقدَّم الخدمة عبر العنوان https://api.minimax.io، وتستقبل طلبات JSON، وتتوافق مع استدعاءات images.generate وimages.edit في OpenAI SDK، بحيث يحتاج معظم الأكواد الحالية للصور إلى تعديل عنوان URL الأساسي واسم النموذج فقط.

والأوزان متاحة للعموم أيضًا: تُدرج بطاقة النموذج على Hugging Face محوّل انتشار (diffusion transformer) بعدد معاملات 33.1 مليار بموجب ترخيص MiniMax-H3-Image Community License. تتطلب الاستضافة الذاتية نحو 69 غيغابايت لنقطة التفتيش إضافة إلى مُرمِّز نصي بحجم 66.7 غيغابايت، لذا تظل الواجهة البرمجية هي الخيار العملي لمعظم الفرق.

أما الجانب المستضاف، بحسب مرجع الواجهة البرمجية من MiniMax بتاريخ 2026-11-11:

احصل على مفتاح MiniMax API الخاص بك

1. سجّل الدخول إلى منصة MiniMax للمطوّرين.
2. افتح إدارة الحساب، ثم API Keys، وأنشئ مفتاحًا.
3. أضف رصيدًا. أي طلب دون رصيد كافٍ يفشل برمز HTTP 402 ورمز الخطأ 1008 (رصيد غير كافٍ).
4. صدّر المفتاح بحيث يقرأه كودك ووكيلك من بيئة التشغيل، لا من ملف ترفعه إلى المستودع:

export MINIMAX_API_KEY="your-key-here"

يُرسَل المفتاح مع كل استدعاء بصيغة Authorization: Bearer $MINIMAX_API_KEY.

طلبك الأول للتحويل من نص إلى صورة

يحتاج أبسط استدعاء مفيد إلى model وprompt وإما حجم دقيق أو فئة مساحة:

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 وأوقف إعادة المحاولة:

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 مهم. فنقطة النهاية ليست idempotent: الخادم يُكمل المهمة ويحصّل قيمتها حتى لو انتهت مهلة عميلك، لذا فإن إعادة المحاولة التلقائية تعني فوترة مزدوجة. اضبط بدلًا من ذلك مهلة 600 ثانية.

معاملات الطلب المهمة

تتحكم في حجم الناتج بإحدى طريقتين، ولا يمكن الجمع بينهما.

بكسلات دقيقة. اضبط size على WIDTHxHEIGHT، مثلًا 4096x4096. يجب أن تقع المساحة الإجمالية بين 655,360 و20,000,000 بكسل، ونسبة العرض إلى الارتفاع بين 1:3 و3:1. لا ترسل aspect_ratio أو area في هذا الوضع، ولا حتى بقيمة auto، وإلا حصلت على خطأ 400.

فئة مع نسبة أبعاد. اترك size بقيمة auto واضبط area (1K أو 2K أو 4K، والافتراضي 4K) وaspect_ratio (أي نسبة X:Y من 1:3 إلى 3:1). يحسب الخادم عدد البكسلات؛ فقيمة 2K بنسبة 16:9 تعيد 2720 x 1536.

أما الحقول الأخرى:

هناك قاعدتان توقعان كثيرين من المستخدمين. أولًا، إذا أوقفت تحسين الـ prompt، فعليك تحديد size دقيق أو aspect_ratio صريح؛ وإلا أرجعت auto خطأ 400. ثانيًا، يفرض b64_json حدًا أقصى لمساحة الناتج الإجمالية: 20,000,000 بكسل لصيغة PNG (صورة واحدة بأي حجم) و80,000,000 لصيغتي JPEG أو WebP (أربع صور 4K أو عشر صور 2K). للدفعات الأكبر، استخدم روابط URL.

تذكر بطاقة النموذج أن H3-Image يعمل بأفضل أداء عند نحو 16 ميجابكسل: 4096x4096 (1:1)، أو 5472x3072 (16:9)، أو 6272x2688 (21:9).

حرّر الصور بما يصل إلى 16 مرجعًا

يستخدم التحرير الحقول نفسها مع مصفوفة images إضافية. أشر إلى المدخلات حسب موقعها في الـ prompt ("الصورة 1"، "الصورة 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"])

تستقبل نقطة النهاية أيضًا الصيغة multipart/form-data، وهي ما يرسله استدعاء images.edit من OpenAI SDK عند رفع الملفات. الحدود بحسب مرجع التحرير:

• من 1 إلى 16 صورة بصيغ JPG أو PNG أو WebP أو HEIC أو HEIF
• كل ضلع بين 128 و8,192 بكسل، بنسبة الطول إلى العرض لا تتجاوز 4:1
• إجمالي جسم الطلب حتى 64 ميجابايت؛ وتضيف base64 نحو الثلث، فاستخدم روابط URL عمومية للمدخلات الكبيرة

اقرأ الاستجابة وعالج الأخطاء

يعيد الاستدعاء الناجح عنصر data واحدًا لكل صورة مطلوبة، بالترتيب:

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

ثلاث عادات تحافظ على سلامة تكاملتك:

1. افحص كل عنصر بحثًا عن error. رمز حالة HTTP يكون 200 إذا نجحت صورة واحدة على الأقل، لذا فرمز 200 لا يعني عودة كل الصور المطلوبة بعدد n. أما إذا فشلت جميع الصور، فستحصل بدلًا من ذلك على 402 أو 422 أو 500.
2. نزّل روابط URL فورًا. يوضح MiniMax أن الرابط غير مضمون البقاء متاحًا، لذا انسخ الملف إلى مخزنك الخاص.
3. سجّل request_id. فهو معرّف التتبع الذي يطلبه فريق الدعم.

تتجاوز حدود المعدل برمز 429. يعني الرمز 1002 أنك تجاوزت حد الصور في الدقيقة، وكل طلب يُحتسب بعدد n من الصور، فدفعة من 10 صور تستهلك 10 من حصتك دفعة واحدة.

أسعار MiniMax H3-Image وخصم الإطلاق

الفوترة تُحتسب لكل رمز (token)، ولا تدفع إلا عن الصور التي نجحت. بحسب صفحة الأسعار من MiniMax، كما قرأناها بتاريخ 2026-11-11:

ينشر MiniMax أيضًا أمثلة على التكلفة لكل صورة للنموذج القياسي:

يكلف Highspeed نحو 1.6 إلى ضعفين لكل صورة ($0.13001 لدقة 4K، و$0.06501 بعد الخصم). ويغيّر طول الـ prompt جانب الدخل، فاعتبر هذه الأرقام تقديرات.

عرض الإطلاق: حتى 17 نوفمبر 2026 الساعة 16:00 بتوقيت UTC، يخفض MiniMax التكلفة الإجمالية للطلب بنسبة 50% لكلا النموذجين عندما تبلغ الصورة المستلمة 16,600,000 بكسل على الأقل. صورة 4096x4096 (16,777,216 بكسل) مؤهلة؛ أما صورة 2K فليست كذلك. تبحث بدلًا من ذلك عن خيارات مجانية؟ راجع كيفية استخدام MiniMax H3-Image مجانًا.

دع وكيل البرمجة يختبرها باستخدام Apidog CLI

تفشل واجهات الصور بصمت: رمز 200 مع نصف الصور مفقود، أو قاعدة حجم نسيتها. بدلًا من فحص الاستجابات يدويًا، دع وكيل البرمجة لديك (Claude Code أو Codex أو Cursor) يبني اختبارًا قابلًا للتكرار باستخدام Apidog CLI.

جهّز الإعداد مرة واحدة:

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

ثم أعطِ وكيلك توجيهًا واحدًا:

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.

يقرأ الوكيل مخطط كل حمولة، ويتحقق من صحة JSON، وينشئ الموارد، ويشغّل حالة الاختبار:

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 مفتاحك وقت التشغيل، فلا يصل أبدًا إلى أي ملف محفوظ. يطبع مراسل cli كل تأكيد كنتيجة نجاح أو فشل؛ ويكتب json تقريرًا يعيد وكيلك قراءته. أبقِ الاختبار عند 1K: فكل تشغيل هو توليد حقيقي يخضع للفوترة. ويُشغَّل السطر نفسه في CI باستخدام -r junit (راجع دليل Apidog CLI CI/CD وApidog CLI في Claude Code). تغطي الخطة المجانية من Apidog ما يصل إلى 4 مستخدمين.

قياسي أم Highspeed: أي معرّف نموذج؟

يستقبل كلا المعرّفين المعاملات نفسها، لذا فالتبديل مجرد تغيير نص واحد. استخدم MiniMax-H3-Image للأصول النهائية والدفعات الحساسة من حيث التكلفة، وMiniMax-H3-Image-Highspeed للمعاينات التفاعلية التي تتفوق فيها سرعة الاستجابة على السعر. لا يقدم مرجع الواجهة البرمجية رقمًا لزمن الاستجابة، فقِسه بنفسك على نصوصك التوجيهية. هل تقارن البدائل؟ اقرأ MiniMax H3-Image مقابل Nano Banana 2.1 أو دليل واجهة Nano Banana 2.1 API أو دليل واجهة GPT Image 2.6 API.

الأسئلة الشائعة

ما هو معرّف نموذج MiniMax H3-Image؟ استخدم MiniMax-H3-Image للنموذج القياسي أو 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، لأن إعادة المحاولة تنشئ عمليات توليد جديدة تخضع للفوترة.

كم صورة مرجعية يمكنني استخدامها للتحرير؟ من 1 إلى 16 صورة لكل طلب، كل منها بين 128 و8,192 بكسل لكل ضلع، بجسم طلب إجمالي أقل من 64 ميجابايت.

كم تكلفة صورة واحدة من MiniMax H3-Image؟ تشير أمثلة MiniMax إلى نحو $0.022 لاستدعاء قياسي من نص إلى صورة بدقة 1K، ونحو $0.069 بدقة 4K، مع خفض 4K إلى النصف لنحو $0.034 حتى 17 نوفمبر 2026 الساعة 16:00 بتوقيت UTC.

لماذا حصلت على رمز 200 مع صور أقل مما طلبت؟ النجاح الجزئي يعيد رمز 200. والعناصر الفاشلة، بما فيها العناصر المحجوبة بسبب فحص السلامة، تحمل كائن error بدل url، ولا تُحتسب عليك تكاليفها.