بدء الاستخدام السريع لـ Z Image Turbo لتوليد الصور من النص بسرعة مع LoRA

Z Image Turbo متاح على Novita AI من خلال نقطتي نهاية غير متزامنتين: POST https://api.novita.ai/v3/async/z-image-turbo لتوليد الصور من النص القياسي، و POST https://api.novita.ai/v3/async/z-image-turbo-lora للتوليد باستخدام نماذج أسلوب LoRA. تتبع كلتا النقطتين النمط غير المتزامن القياسي لـ Novita AI — أرسل طلبًا، واستلم task_id، ثم استقصِ GET /v3/async/task-result حتى تصبح الصورة جاهزة. يغطي هذا الدليل كلا النقطتين من البداية إلى النهاية: الطلب الأول، حلقة الاستقصاء، استخدام LoRA، ومرجع المعلمات الذي تحتاجه قبل كتابة كود الإنتاج.

متى تستخدم دليل البدء السريع هذا

استخدم هذا الدليل عندما تحتاج إلى طلب عمل موثوق لـ Z Image Turbo قبل إضافة معالجة الأخطاء أو التجميع أو منطق الإنتاج حوله.

Z Image Turbo مصمم للإنتاجية السريعة. يناسب سير العمل حيث:

• السرعة أهم من الجودة القصوى — خطوط أنابيب النماذج الأولية، توليد معاينات دفعية، أو تطبيقات الوقت الفعلي حيث زمن الانتقال قيد صارم.
• تريد نقل الأسلوب المستند إلى LoRA دون تهيئة مجموعة معلمات txt2img الكاملة. تقبل نقطة نهاية LoRA المخصصة مصفوفة loras وتتعامل مع الباقي.
• تحتاج واجهة بسيطة: إدخال موجه / إخراج صورة مع نص طلب صغير الحجم.

Z Image Turbo ليس الخيار المناسب عندما تحتاج إلى سطح تهيئة كامل لنموذج Stable Diffusion — steps, guidance_scale, sampler_name, negative_prompt, hires_fix, نماذج المكرر، وما إلى ذلك. لمثل هذا المستوى من التحكم، استخدم نقطة النهاية القياسية POST /v3/async/txt2img.

يغطي هذا الدليل مسار API المستضاف على Novita AI فقط. لا يتناول الاستضافة الذاتية أو الضبط الدقيق.

الخطوة 1: الحصول على مفتاح API الخاص بـ Novita

أنشئ حسابًا على Novita AI وانتقل إلى إدارة مفتاح API. قم بتوليد مفتاح وتصديره:

export NOVITA_API_KEY="your_api_key_here"

احتفظ بالمفتاح بعيدًا عن التحكم بالإصدارات، الحزم الجانبية للعميل، وطبقات صور Docker.

الخطوة 2: تأكيد نقاط النهاية

يستخدم Z Image Turbo على Novita AI نقطتي إرسال منفصلتين ونقطة نهاية مشتركة واحدة للنتائج:

	T2I أساسي	T2I LoRA
الإرسال	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
استقصاء النتيجة	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
مرجع API	وثائق Z Image Turbo	وثائق Z Image Turbo LoRA

تعيد نقطتا الإرسال فقط task_id. نقطة نهاية استقصاء النتيجة متطابقة لكليهما — بمجرد أن تعمل حلقة الاستقصاء الخاصة بك لواحدة، فإنها تعمل للأخرى.

الخطوة 3: إرسال طلبك الأول

تتطلب نقطة النهاية الأساسية prompt و size. ابدأ هنا قبل إضافة المعلمات الاختيارية:

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at dusk, neon lights, photorealistic, ultra-detailed",
    "size": "1024*1024"
  }'

الاستجابة الناجحة 200 ترجع:

{
  "task_id": "abc123..."
}

احفظ task_id. لا يُرجع أي شيء آخر عند الإرسال — يعمل التوليد بشكل غير متزامن.

معلمتان اختياريتان متاحتان على نقطة النهاية الأساسية:

• seed (عدد صحيح): لتثبيت النتائج القابلة للتكرار. نفس مجموعة الموجه والبذور تعطي نتائج متناسقة.
• enable_base64_output (قيمة منطقية): عندما تكون true، تتضمن النتيجة الصورة كسلسلة مشفرة بـ base64 بدلاً من رابط مستضاف.

الخطوة 4: استقصاء النتيجة

استخدم GET على نقطة نهاية نتيجة المهمة مع task_id كمعامل استعلام:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

مهمة مكتملة ترجع:

{
  "task": {
    "task_id": "abc123...",
    "status": "TASK_STATUS_SUCCEED",
    "progress_percent": 100,
    "eta": 0
  },
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": 3600,
      "image_type": "png"
    }
  ]
}

استقصِ كل 1-2 ثانية حتى يصبح task.status إما TASK_STATUS_SUCCEED أو TASK_STATUS_FAILED. حقل task.eta يعطي الثواني المتبقية المقدرة عندما تكون المهمة لا تزال في قائمة الانتظار.

image_url_ttl هو عمر الرابط بالثواني. قم بتنزيل الصورة وتخزينها قبل انقضاء TTL — الرابط المستضاف ليس دائمًا.

الخطوة 5: التحقق من الأسعار والحدود والأخطاء الشائعة

الأسعار الحالية لـ Z Image Turbo مدرجة على صفحة تسعير Novita AI و صفحة نموذج Z Image Turbo. تحقق من الأسعار قبل بناء تقديرات التكلفة، حيث يمكن أن تتغير الأسعار.

الأخطاء الشائعة:

الخطأ	السبب	الحل
401 غير مصرح	مفتاح API مفقود أو غير صحيح	تأكد من أن الرأس هو Authorization: Bearer <key>
400 طلب غير صحيح	جسم الطلب غير صالح	تأكد من أن prompt و size عبارة عن سلاسل نصية؛ seed يجب أن يكون عددًا صحيحًا إذا تم توفيره
TASK_STATUS_FAILED	رفض التوليد أو خطأ	اقرأ task.reason في استجابة النتيجة للحصول على رسالة الفشل المحددة
رابط الصورة يرجع 403 أو منتهي الصلاحية	تم الوصول إلى الرابط بعد انقضاء TTL	قم بتنزيل الصورة وتخزينها قبل مرور image_url_ttl ثانية

مثال بلغة Python

سير العمل الكامل — إرسال، استقصاء، إرجاع رابط الصورة:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_image(prompt: str, size: str = "1024*1024", seed: int = None) -> str:
    payload = {"prompt": prompt, "size": size}
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

if __name__ == "__main__":
    url = generate_image(
        "A futuristic city skyline at dusk, neon lights, photorealistic",
        size="1024*1024",
        seed=42,
    )
    print(url)

توليد LoRA

تضيف نقطة نهاية LoRA مصفوفة loras إلى الطلب. يأخذ كل مدخل path (معرّف نموذج LoRA من مركز نماذج Novita AI) و scale (وزن التأثير):

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo-lora \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a portrait in anime style, soft lighting, detailed face",
    "size": "768*1024",
    "loras": [
      {
        "path": "<lora-model-path>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

استبدل <lora-model-path> بمسار مؤكد من مركز نماذج Novita AI. تنسيق path ونماذج LoRA المتوافقة مدرجة في مرجع API Z Image Turbo LoRA — لا تخمن مسارات النماذج؛ استخدم فقط إدخالات المركز المؤكدة لتجنب نتائج TASK_STATUS_FAILED من مسارات غير قابلة للحل.

استقصاء نتيجة LoRA يعمل تمامًا مثل نقطة النهاية الأساسية.

نسخة Python لنفس سير عمل LoRA:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_with_lora(
    prompt: str,
    lora_path: str,
    lora_scale: float = 0.8,
    size: str = "1024*1024",
    seed: int = None,
) -> str:
    payload = {
        "prompt": prompt,
        "size": size,
        "loras": [{"path": lora_path, "scale": lora_scale}],
    }
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo-lora",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

إرشادات مقياس LoRA

scale يتحكم في مدى قوة تطبيق أسلوب LoRA. قيمة 0.8 هي إعداد افتراضي معقول. اخفض (0.4–0.6) إذا كانت تفاصيل الموجه يتم تجاوزها بواسطة أسلوب LoRA؛ ارفع (0.9–1.0) إذا كان الأسلوب لا يظهر بقوة كافية. تكديس عدة LoRAs بقيم scale عالية يمكن أن يقلل من التماسك — اختبر كل LoRA بشكل منفصل أولاً.

تتطلب بعض نماذج LoRA كلمات تشغيل في الموجه لتفعيل أسلوبها. تحقق من قائمة النموذج في مركز Novita AI لأي كلمات رئيسية مطلوبة قبل الاختبار.

المعلمات الرئيسية

نقطة النهاية الأساسية (/v3/async/z-image-turbo)

المعامل	النوع	مطلوب	الوصف
prompt	سلسلة نصية	نعم	وصف نصي للصورة المستهدفة
size	سلسلة نصية	نعم	أبعاد الإخراج بصيغة "width*height"، مثلاً "1024*1024"
seed	عدد صحيح	لا	مثبت للتكرار؛ نفس البذور + الموجه يعطي مخرجات متناسقة
enable_base64_output	قيمة منطقية	لا	عندما تكون true، تُرجع الصورة كسلسلة base64 بدلاً من رابط مستضاف

نقطة نهاية LoRA (/v3/async/z-image-turbo-lora)

المعامل	النوع	مطلوب	الوصف
prompt	سلسلة نصية	نعم	موجه نصي؛ تضمين كلمات تشغيل LoRA إذا لزم الأمر
size	سلسلة نصية	نعم	أبعاد الإخراج بصيغة "width*height"
loras	مصفوفة	نعم	كائن LoRA واحد أو أكثر
loras[].path	سلسلة نصية	نعم	مسار نموذج LoRA من مركز نماذج Novita AI
loras[].scale	رقم	نعم	وزن التأثير؛ 0.8 نقطة بداية شائعة
seed	عدد صحيح	لا	مثبت التكرار

enable_base64_output غير مدرج على نقطة نهاية LoRA في الوثائق الحالية. استخدم رابط النتيجة من الاستقصاء لاسترجاع الصورة.

استكشاف الأخطاء وإصلاحها

المهمة تبقى في حالة TASK_STATUS_PENDING لفترة أطول من المتوقع. يختلف عمق قائمة الانتظار حسب حمل المنصة. حقل task.eta في استجابة الاستقصاء يعيد وقت الانتظار المقدر بالثواني. لمسارات الإنتاج الحساسة لزمن الانتقال، فكر في إرسال الطلبات والاستقصاء بالتوازي عبر عدة معرفات مهام.

TASK_STATUS_FAILED فورًا أو بعد انتظار قصير. اقرأ task.reason في النتيجة. الأسباب الشائعة: تنسيق سلسلة size غير صالح، مسار LoRA غير قابل للحل، أو موجه أدى إلى تصفية المحتوى. اعزل المشكلة بطلب صغير الحجم.

رابط الصورة يُرجع 403. عمر الرابط يتحكم به image_url_ttl (بالثواني). إذا طلبت الرابط بعد تلك النافذة، سيتم رفض الوصول. قم بجلب بيانات الصورة وتخزينها فور نجاح الاستقصاء.

أسلوب LoRA لا يظهر في الإخراج. حاول زيادة scale نحو 1.0. تحقق مما إذا كان LoRA يتطلب كلمات تشغيل — إذا كان كذلك، أضفها إلى الموجه.

400 Bad Request على نقطة نهاية LoRA. تأكد من أن حقل loras هو مصفوفة (وليس كائنًا)، وأن كلاً من path و scale موجودان في كل مدخل.

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

ما هو الغرض من Z Image Turbo؟

Z Image Turbo مُحسَّن لتوليد الصور من النص بسرعة. يناسب التطبيقات التي تحتاج إلى إنتاجية سريعة: توليد المعاينات، خطوط أنابيب الدفعات، وحالات الاستخدام حيث يكون التصميم المستند إلى LoRA أكثر أهمية من التحكم الدقيق في الانتشار لسير عمل SDXL الكامل.

ما الأحجام التي يدعمها Z Image Turbo؟

المعامل size يأخذ سلسلة "width*height". القيم المدعومة المؤكدة مدرجة على صفحة نموذج Z Image Turbo. التنسيق المربع (1024*1024) والتنسيق العمودي (768*1024) نقطة بداية آمنة، متسقة مع نقاط نهاية الصور الأخرى لـ Novita AI.

هل يمكنني تطبيق عدة LoRAs في طلب واحد؟

المصفوفة loras تقبل عدة مدخلات. عمليًا، تكديس LoRAs بقيم scale عالية غالبًا ما يقلل من جودة الإخراج. اختبر كل LoRA بشكل منفصل أولاً، ثم ادمجها بقيم scale متحفظة (0.5–0.7 لكل مدخل).

أين أجد مسارات LoRA المتوافقة؟

تصفح مركز نماذج Novita AI وتحقق من مرجع API Z Image Turbo LoRA للحصول على تنسيق المسار المؤكد. لا تستخدم مسارات من مصادر خارجية دون التحقق أولاً من أنها قابلة للحل على منصة Novita.

هل negative_prompt مدعوم؟

لا تدرج أي من نقطتي نهاية Z Image Turbo معامل negative_prompt في الوثائق الحالية. إذا كنت بحاجة إلى استبعاد مواضيع أو أنماط، استخدم صياغة إيجابية في الموجه لتوجيه الابتعاد عن المحتوى غير المرغوب فيه، أو قيّم نقطة النهاية القياسية txt2img التي تدعم negative_prompt مباشرة.

هل يمكنني توليد صور متعددة في استدعاء واحد؟

الوثائق الحالية لا تدرج معامل image_num على أي من نقطتي نهاية Z Image Turbo. للتوليد الدفعي، أرسل طلبات متعددة بالتوازي واستقصِ قيم task_id الخاصة بها بالتزامن — كل طلب مستقل.

كيف يقارن Z Image Turbo بنقطة النهاية القياسية txt2img؟

تدعم نقطة النهاية القياسية txt2img سطح تهيئة واسع: الخطوات، مقياس التوجيه، المُعيّن، الموجه السلبي، Hi-Res Fix، ونماذج المكرر. Z Image Turbo يستبدل تلك القابلية للتهيئة بالسرعة وشكل الطلب الأبسط. استخدم txt2img عندما تكون التحكم في المعلمات مهمًا؛ استخدم Z Image Turbo عندما تكون الإنتاجية أو البساطة هي الأولوية.

المقالات الموصى بها

• بدء الاستخدام السريع لـ Qwen Image لتوليد الصور من النصوص
• FLUX.1 Kontext Pro مقابل Max مقابل Dev على Novita AI
• إضافة LoRA Stable Diffusion: دليل شامل