كيفية إعداد إنشاء الصور بالجملة عبر OpenArt CLI

قبل أن تكتب أي سكربت

يفترض هذا الدرس أن الملف الثنائي مثبّت ومُصادَق عليه. وإن لم يكن كذلك، ثبّته بأمر واحد وسجّل الدخول عبر المتصفح.

curl -fsSL https://raw.githubusercontent.com/OpenArt-AI/cli/main/install.sh | sh
openart login

تأكد من الحساب والخطة ورصيد الأرصدة قبل وضع دفعة في قائمة الانتظار تنفق أرصدة حقيقية.

openart account

لمعرفة خطوات التثبيت على Windows، أو تثبيت إصدار محدد، أو المرجع الكامل للأوامر، راجع مستودع CLI على GitHub بدلاً من تكرار الإعداد هنا.

تحقّق من ملاءمة النموذج وتكلفته قبل أن تنفق أي شيء

اختر نموذجًا يدعم إنشاء الصور من النص قبل بناء حلقة الدفعة. قد تتغير النماذج المتاحة وقدراتها مع إضافة OpenArt خيارات جديدة، لذا تجنّب الاعتماد على اسم تحفظه أو افتراض ضمني.

openart model list

راجع النماذج المتاحة، وأكّد دعم التحويل من نص إلى صورة، وانسخ معرّف النموذج الذي تريد استخدامه. خزّن المعرّف في متغير لتقليل أخطاء التحرير في الأوامر اللاحقة.

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

openart model form "$MODEL_ID" text2image

MODEL_ID="<model-id>"

تحقق من سعر النموذج لكل صورة قبل إرسال أي مهام.

openart model cost \
  --model "$MODEL_ID" \
  --mode text2image

الـ model cost يعيد الأمر عرض سعر فقط. ولا ينشئ صورة ولا ينفق أرصدة. شغّله دون أي وسائط لعرض سعر كل نموذج من الأرخص أولًا، أو حدده لنموذج ووضع واحد كما هو موضح أعلاه. اضرب التكلفة المعروضة لكل صورة بعدد الصور المخطط لها لتقدير تكلفة الدفعة. إذا كان ملف CSV يخصص نماذج مختلفة لصفوف مختلفة، فاطلب عرض سعر لكل نموذج واحسب كل مجموعة على حدة.

عاين الطلب الدقيق باستخدام ‎--dry-run

شغّل مُوجّهًا تمثيليًّا واحدًا باستخدام النموذج والأعلام نفسها المخطط لها للدفعة.

MODEL_ID="your-model-id"
openart generate image \
  "A red bicycle leaning against a brick wall at sunset" \
  --model "$MODEL_ID" \
  --json \
  --async \
  --dry-run

يطبع الأمر الطلب الذي سيرسله OpenArt، بما في ذلك الموجه والنموذج ومعاملات الإنشاء. لا يرسل OpenArt أي مهمة ولا ينفق أرصدة أثناء التشغيل التجريبي.

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

تنسيق قائمة الموجّهات

استخدام prompts.txt عندما تتشارك كل مهمة النموذج والمعاملات نفسها. خزّن موجهًا كاملًا واحدًا لكل سطر.

A watercolor cabin beside a frozen lake
A studio photo of a red ceramic teapot
An isometric library with warm lighting

احتفظ بكل مطالبة على سطر مادي واحد. سطر لاحق read -r تحافظ الحلقة على الشرطات المائلة العكسية، والاقتباس "$prompt" يمرّر المسافات وعلامات الاقتباس كجزء من الموجه. تخطَّ الأسطر الفارغة ما لم تكن تنوي إرسال موجه فارغ.

استخدام prompts.csv عندما تحتاج الصفوف إلى نماذج أو أبعاد مختلفة.

prompt,model,width,height
"A cabin beside a lake","model-id-a",1024,1024
"A teapot, red ceramic","model-id-b",768,1024
"A sign reading ""OPEN""","model-id-a",1024,768

يجب أن تستخدم حقول CSV التي تحتوي على فواصل علامات اقتباس مزدوجة. مثّل علامة اقتباس داخل حقل مقتبس بعلامتي اقتباس. حلقة طرفية تعتمد على IFS=, لا يمكنه تحليل تلك الحالات بشكل صحيح، لذا ينبغي أن يستخدم متغير CSV محللًا مدركًا لـ CSV مثل محلل Python csv الوحدة. حافظ على ثبات أسماء العناوين لأن النص اللاحق يقرأها مباشرةً.

أرسل الدفعة باستخدام حلقة while-read

احفظ النص التالي باسم submit.sh. يقرأ مطالبة واحدة في كل سطر، ويرسل كل عملية إنشاء، ويلحق كل معرّف مهمة مُرجَع إلى job-ids.txt.

#!/usr/bin/env bash
set -uo pipefail
MODEL_ID="replace-with-model-id"
PROMPT_FILE="${1:-prompts.txt}"
JOB_FILE="${2:-job-ids.txt}"
printf '' > "$JOB_FILE"
while IFS= read -r prompt || [[ -n "$prompt" ]]; do
  [[ -z "$prompt" ]] && continue
  if ! response=$(openart generate image "$prompt" \
    --model "$MODEL_ID" \
    --json \
    --async); then
    printf 'Submission failed for prompt %s\n' "$prompt" >&2
    continue
  fi
  if ! job_id=$(jq -er '.id' <<&2
    continue
  fi
  printf '%s\n' "$job_id" >> "$JOB_FILE"
  printf 'Submitted %s\n' "$job_id" >&2
done &2

استبدال replace-with-model-id، اجعل النص قابلًا للتنفيذ، ومرّر ملف موجهات مختلفًا عند الحاجة.

chmod +x submit.sh
./submit.sh prompts.txt

يتطلب السكربت jq لاستخراج المعرّف من كل استجابة JSON. إذا كان الـ CLI المثبت لديك يُرجع المعرّف تحت حقل مختلف، فافحص استجابة واحدة واضبط .id التعبير.

الـ --json يبقي العلم الإخراج القياسي قابلاً للقراءة آليًا. يرسل OpenArt رسائل التقدم والترقيم إلى الخطأ القياسي، لذا يلتقط استبدال الأمر فقط الـ JSON الذي jq يحتاج. بدون --json، قد يدخل الإخراج القابل للقراءة البشرية إلى response المتغير ويتسبب في فشل تحليل المعرّف.

الـ --async يجعل العَلَم كل أمر يعود بعد أن يقبل OpenArt المهمة. بدونه، تنتظر الحلقة صورة واحدة قبل إرسال التالية وقد تنتظر حتى المهلة الافتراضية البالغة خمس دقائق لكل مُوجّه. يتيح الإرسال غير المتزامن للحلقة إدراج الدفعة الكاملة في قائمة الانتظار أولًا.

يضيف كل إرسال ناجح معرّفًا واحدًا إلى job-ids.txt.

job_abc123
job_def456
job_ghi789

يمكن لحلقة التجميع استهلاك ذلك الملف مباشرةً. تُنتج عمليات الإرسال الفاشلة خطأً على المخرج القياسي للخطأ ولا تضيف إدخالًا غير صالح إلى الملف.

شغّل متغير CSV

تقسم حلقة CSV كل صف إلى حقول وتمرر نموذج الصف إلى أمر التوليد.

#!/usr/bin/env bash
> job-ids.txt
tail -n +2 prompts.csv |
while IFS=, read -r prompt model
do
  model=${model%$'\r'}
  [ -z "$prompt" ] && continue
  response=$(
    openart generate image "$prompt" \
      --model "$model" \
      --json \
      --async
  ) || continue
  printf '%s\n' "$response" |
    jq -r '.id' >> job-ids.txt
done

مقارنةً بحلقة النص العادي، IFS=, read -r prompt model يقسّم كل صف، و --model "$model" يحل محل معرّف النموذج الثابت. الـ tail يتخطى الأمر صف العناوين مثل prompt,model.

لا يطبّق تقسيم حقول Bash قواعد اقتباس CSV الكاملة. إذا احتوت المُوجّهات على فواصل أو علامات اقتباس مهرّبة، فحلّل الملف باستخدام csv وحدة أو أداة أخرى داعمة لصيغة CSV قبل تمرير الحقول إلى أمر OpenArt.

اجمع النتائج بعد إرسال كل شيء

استخدام openart creation wait عندما يجب أن ينتهي البرنامج النصي فقط بعد أن تصل كل مهمة مُرسَلة إلى حالة نهائية. تحفظ الحلقة كل سجل إنشاء مكتمل بصيغة JSON وتسجّل أي مهام تُرجع خطأً.

mkdir -p results
: > failed_job_ids.txt
while IFS= read -r job_id; do
  [ -z "$job_id" ] && continue
  if openart creation wait "$job_id" --json \
    > "results/${job_id}.json"; then
    printf 'Completed %s\n' "$job_id"
  else
    printf '%s\n' "$job_id" >> failed_job_ids.txt
    printf 'Failed %s\n' "$job_id" >&2
  fi
done < job_ids.txt

يحتوي كل ملف JSON على بيانات الإنشاء النهائية، بما في ذلك معلومات الأصل المُرجَعة. يمكن لخطوة المعالجة التالية قراءة تلك الملفات وتنزيل الصور المُولّدة أو نقلها حسب الحاجة.

استخدام openart creation get عندما تريد فحص حالة واحدة دون حجب. يمكن لفحص يدوي أو مهمة استطلاع مجدولة تشغيل الحلقة نفسها مع تغيير أمر واحد.

mkdir -p status
while IFS= read -r job_id; do
  [ -z "$job_id" ] && continue
  openart creation get "$job_id" --json \
    > "status/${job_id}.json"
done < job_ids.txt

الـ wait تتوقف الحلقة عند كل معرّف، لكنها لا تجعل توليد الصور متسلسلًا. تبدأ كل مهمة بعد الإرسال غير المتزامن السابق، لذا تستمر المهام اللاحقة في العمل بينما تنتظر الحلقة الأولى. في CI، wait يوفّر نقطة اكتمال واضحة. للمراقبة اليدوية، get يتيح لك فحص الحالات الراهنة والعودة فورًا.

ما الذي يمكن لواجهة OpenArt CLI فعله أيضًا

يركّز هذا الدرس على سير عمل واحد: تحويل قائمة من الموجهات النصية إلى دفعة من الصور. تغطي واجهة CLI أكثر من ذلك بكثير، ويستحق الأمر معرفة ما هو متاح قبل بناء أدوات منفصلة له.

يمكنه أيضًا تعديل صورة لديك بالفعل. وجّهه نحو صورة على جهازك أو رابط، وصِف التعديل المطلوب، لتحصل على نسخة جديدة بدلًا من التوليد من الصفر فقط. أما بالنسبة للفيديو، فيمكنه إنشاء فيديو من وصف نصي، أو بثّ الحياة في صورة ثابتة، مع تحكمك في الطول والشكل والدقة أينما سمح النموذج المختار بذلك.

إلى جانب الإنشاء، تبقيك واجهة CLI منظمًا: بدّل بين المشاريع ومساحات العمل، وارفع صورة مرجعية مرة واحدة لإعادة استخدامها عبر الموجهات اللاحقة بدلًا من رفع الملف نفسه في كل مرة. يمكن الاحتفاظ بكل نتيجة كرابط قابل للمشاركة أو تنزيلها مباشرةً إلى مجلد، ويمكنك مراجعة كل ما أنشأته، أو فحص مهمة لا تزال قيد التشغيل، أو انتظار اكتمال إحداها.

None of that changes the batch pattern in this tutorial. It just means the same terminal-first approach extends past plain text-to-image jobs. See OpenArt's نظرة عامة على واجهة CLI للأوامر الكامنة وراء كل من هذه.

أين يُستخدم سير عمل الدفعات هذا فعليًا

تشرح بضع حالات ملموسة سبب لجوء الفرق إلى دفعة مكتوبة بالسكربت بدلاً من تطبيق الويب.

متغيرات كتالوج المنتجات. فريق تجارة إلكترونية لديه جدول بيانات يضم 500 وحدة تخزين (SKU) ينشئ واحدة صورة المنتج لكل صف بتمرير أوصاف المنتجات عبر متغير CSV، مع مطابقة النموذج والأبعاد في كل صف مع المكان الذي ستُعرض فيه الصورة (مربّع لشبكة منتجات، طولي لإعلان قصة).

جدران أصول المحتوى. يحتاج فريق المحتوى أو النمو إلى 50 متغيرات الصور المصغّرة لاختبار A/B قبل الغداء. تُرسل قائمة المطالبات في ملف نصي وحلقة while-read جميع الـ 50 في نفس الوقت الذي تستغرقه لكتابة المطالبات، بدلاً من النقر عبر تطبيق الويب 50 مرة.

مجموعات إبداعية مُوطّنة. يحوّل فريق تسويق المفهوم الأساسي نفسه إلى مجموعة من تصميم إعلاني متغيرات عبر عشرات المُوجّهات، لكل منها إعداد أو نموذج أو نسبة أبعاد مختلفة لسوق أو قناة محددة، باستخدام متغير CSV لتغيير تلك الحقول لكل صف.

خطوط أنابيب CI والوكلاء. مهمة ليلية تعيد إنشاء مجموعة ثابتة من صور المعاينة كلما تغيّرت بيانات المصدر، أو وكيل يشغّل بالفعل أوامر الطرفية ويرسل الإنشاءات كجزء من سير عمل أوسع لاستدعاء الأدوات — النمط نفسه الكامن وراء إنشاء إعلانات المنتجات من Claude. كلاهما يحتاج إلى --json مخرجات ورموز خروج غير تفاعلية، وليس جلسة متصفح.

متى تلجأ إلى سير عمل دفعات CLI بدلاً من تطبيق الويب أو MCP

استخدم سير عمل الدفعات في CLI عندما يحتاج البرنامج النصي إلى إرسال مهام قابلة للتكرار، والحفاظ على معرّفات المهام، وجمع النتائج دون إدخال يدوي. يناسب ذلك عمليات CI المجدولة، وسلاسل معالجة الـshell، ومعالجة المُوجّهات بالجملة، واستدعاءات أدوات الوكلاء التي تنفّذ أوامر الطرفية.

استخدام OpenArt للجلسات الإبداعية الفردية حيث تريد تعديل الموجهات والإعدادات أثناء مراجعة كل نتيجة. OpenArt MCP يُلائم التوليد الحواري داخل وكلاء مثل Claude أو ChatGPT، حيث تتحكم المحادثة في الطلب بدلًا من برنامج نصي للـshell.

If the goal is not just generating images but also routing each result somewhere else automatically, such as posting a finished image to Telegram, Slack, or Discord, that behavior belongs to an agent, not to this batch script. An agent framework that already supports tool calling can call OpenArt MCP to generate the image, then call a separate messaging tool to deliver it. The while-read loop in this tutorial submits jobs and writes results to disk. It does not send anything anywhere, so a delivery step still needs its own script or agent on top of it.

اختر الواجهة التي تناسب طريقة عملك. يغطّي مستودع CLI على GitHub التثبيت والمرجع الكامل للأوامر. تغطّي نظرة MCP العامة أعلاه التوليد القائم على المحادثة، إن كان ذلك يناسب سير عملك أكثر من المعالجة المجمّعة المعتمدة على الملفات.

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

ماذا يحدث إذا فشلت مهمة في منتصف الدفعة؟

لا تُلغي المهمة الفاشلة المهام المُرسَلة مسبقًا. ينبغي لحلقة التجميع تسجيل معرّف المهمة الفاشلة والمتابعة ما لم يخرج البرنامج النصي عند حدوث الأخطاء. افحص المهمة الفاشلة باستخدام openart creation get <job-id>.

كيف أضبط مهلة أطول دون ‎--async؟

الـ --timeout <seconds> يمدد الخيار مدة انتظار أمر الإنشاء المتزامن. على سبيل المثال، أضف --timeout 900 للانتظار حتى 15 دقيقة. تحقق من القيمة المدعومة عبر openart generate image --help.

هل يمكنني استخدام ‎--async مع ‎-o أو ‎--output؟

يُرجع الإرسال غير المتزامن معرّف مهمة قبل وجود الصورة، لذا لا يمكن لأمر الإنشاء حفظ الصورة المكتملة على الفور. خزّن معرّف المهمة أثناء الإرسال بدلاً من ذلك. استخدم openart creation wait <job-id> لاحقًا لجمع النتيجة والتعامل مع مخرجاتها.

كيف أعيد تشغيل المطالبات الفاشلة فقط؟

تتطلب إعادة التشغيل سجلًّا يربط كل مُوجّه بمعرّف المهمة المُرسَلة الخاص به. أثناء التجميع، اكتب المعرّفات الفاشلة ومُوجّهاتها في ملف منفصل. أعِد إدخال ذلك الملف في حلقة الإرسال بعد تصحيح أي مُوجّهات أو معلمات غير صالحة.

هل سيؤدي إرسال مئات المهام دفعة واحدة إلى بلوغ حد المعدل؟

ترسل الحلقة كما هي مكتوبة بأسرع ما يمكن للطرفية أن تكرر، مما قد يتجاوز حد المعدل في دفعة كبيرة. أضف فترة قصيرة sleep 0.5 داخل الحلقة بعد كل إرسال، أو تتبّع عدّادًا وتوقّف لبضع ثوانٍ كل 20 إلى 50 مُوجّهًا، للحفاظ على معدل ثابت للطلبات بدلًا من الاندفاع.

هل يعمل ‎--dry-run مع ‎--async معًا؟

نعم. يعاين دمجهما الطلب الدقيق لمهمة كانت ستُنفّذ بشكل غير متزامن، دون إرسالها أو إنفاق أرصدة. أبقِ كلا العلمين على الأمر النموذجي أثناء الاختبار، ثم أسقط فقط --dry-run عند انتقالك إلى الدفعة الفعلية.

كيف أتتبع الصورة التي نتجت عن كل موجّه؟

لا تحمل معرّفات المهام وحدها نص المُوجّه الأصلي. اكتب المُوجّه ومعرّف مهمته في السطر نفسه من ملف سجل عند الإرسال، على سبيل المثال printf '%s\t%s\n' "$job_id" "$prompt" >> submissions.tsv، حتى تتمكن خطوة لاحقة من مطابقة صورة مكتملة بالمطالبة التي أنتجتها.

أين تنتهي الصور المكتملة؟

openart creation wait و openart creation get تُرجع بيانات المهمة الوصفية وعناوين URL للأصول بصيغة JSON، وليس ملفات الصور نفسها. أضف خطوة تنزيل، مثل curl -o "results/${job_id}.png" "$url" باستخدام عنوان URL من ذلك الـ JSON، إذا كان سير العمل يحتاج إلى ملفات على القرص بدلاً من الروابط.

هل يعمل سير عمل الدفعات هذا لإنشاء الفيديو أيضًا؟

نعم. يعكس CLI أوامر الصور للفيديو: openart generate video "<prompt>" --model kling-3-omni يرسل مهمة فيديو بالطريقة نفسها openart generate image يرسل مهمة صورة. استبدل generate image لـ generate video في حلقة الإرسال، والأمر نفسه --json/--async أعلام بالإضافة إلى openart creation wait/openart creation get ينبغي تطبيق نمط التجميع. شغّل openart generate video --help لتأكيد أي أعلام خاصة بالفيديو (مثل المدة) قبل كتابة برنامج نصي لدفعة كبيرة، إذ تغطّي أمثلة هذا الدرس واختباره توليد الصور تحديدًا.