تخطَّ إلى المحتوى
موارد المطورين
موارد المطورين

CLI

ثبّت واستخدم كل أوامر RunAPI CLI لإجراءات النموذج والمهام والملفات والتحميلات ومعلومات الحساب والتسعير وعمليات الاستدعاء وHarness.

عرض Markdown

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

التثبيت

ثبّت الإصدار الحالي على Linux أو macOS:

SHELL 
curl -fsSL https://runapi.ai/cli/install.sh | sh

تتوفر أيضاً طرق التثبيت عبر Homebrew ومن المصدر باستخدام Go:

SHELL 
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest

على Windows، نزِّل أرشيف windows-amd64 أو windows-arm64 المطابق من أحدث إصدار CLI، واستخرج runapi.exe، وأضفه إلى PATH.

ثبّت المثبّت على إصدار معين أو دليل تثبيت محدد عند الحاجة إلى ثنائي قابل للإعادة الإنتاج:

SHELL 
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"

يقبل المثبّت أيضًا RUNAPI_VERSION وRUNAPI_INSTALL_DIR وRUNAPI_INSTALL_BASE وRUNAPI_DOWNLOAD_BASE وRUNAPI_SKIP_LIBC_CHECK=1.

البدء السريع

على محطة عمل، سجّل الدخول في المتصفح وتحقق من مصدر بيانات الاعتماد:

SHELL 
runapi login
runapi auth status

شغِّل إجراء نموذج بإدخال JSON مضمَّن أو ملف JSON:

SHELL 
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json

معظم إجراءات النموذج غير متزامنة. وتنتظر نتيجة نهائية افتراضيًا؛ أضف --async للإعادة الفورية للمهمة واستخدم wait لاحقًا:

SHELL 
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music

اصطلاحات الأوامر

يُصدر كل أمر JSON على الإخراج القياسي ما لم يطلب خيار ما صراحةً قيمة عددية، مثل files create --url-only أو listen --print-secret. تبقى رسائل التقدم والتشخيص على الخطأ القياسي، لذا يمكن تمرير JSON بأمان إلى jq:

SHELL 
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}

تقبل إجراءات النموذج مصدر إدخال طلب واحد بالضبط:

  • --input '<json object>' يُمرّر JSON مضمّناً.
  • --input-file path/to/request.json يحمّل JSON من ملف.
  • --input-file - يقرأ JSON من الإدخال القياسي.

استخدم runapi <service> <action> --help قبل إنشاء طلب. يعرض CLI المثبت الحقول الحالية للإجراء ومعرّفات النماذج المقبولة وقيود التحقق من الصحة.

تنطبق هذه الخيارات العامة على كل أمر:

الخيار الغرض --api-key استخدام مفتاح API لهذا الاستدعاء. يتجاوز RUNAPI_API_KEY. --base-url استخدام أصل API مختلف لهذا الاستدعاء. --timeout تعيين المهلة الإجمالية للأمر والحد الأقصى لانتظار المهمة. القيمة الافتراضية هي 15 دقيقة. --poll-interval تعيين الفترة الزمنية لاستطلاع المهمة. القيمة الافتراضية هي 3 ثوانٍ. --async العودة فورًا بعد إرسال إجراء نموذج غير متزامن. --quiet إخفاء تقدم العملية على الخطأ القياسي دون تغيير مخرجات JSON.

إجراءات النموذج

شكل أمر النموذج هو runapi <service> <action>. تُعيد الإجراءات المتزامنة استجابتها فورًا. أما الإجراءات غير المتزامنة فالسلوك الافتراضي هو الإرسال والاستطلاع وإعادة نتيجة المهمة النهائية؛ بينما يُعيد --async استجابة الإنشاء بدلاً من ذلك.

بالنسبة لحقول URL الوسائط على المستوى الأعلى، يتم رفع مسار ملف محلي قابل للقراءة قبل تشغيل إجراء النموذج. تُرسَل عناوين URL الحالية التي تبدأ بـ http:// وhttps:// دون تغيير. استخدم files create عندما تحتاج إلى URL مؤقت قابل لإعادة الاستخدام، أو عندما يكون المصدر عنوان URL بعيداً، أو عندما يكون المصدر بيانات Base64.

إجراءات الصوت والموسيقى

  • suno: add-instrumental، add-vocals، blend-lyrics، boost-style، check-voice، convert-audio، cover-audio، create-mashup، extend-music، generate-artwork، generate-lyrics، generate-midi، generate-persona، generate-voice، get-timestamped-lyrics، regenerate-validation-phrase، replace-section، separate-audio-stems، text-to-music، text-to-sound، visualize-music، voice-to-validation-phrase
  • producer: text-to-music
  • gemini-omni: create-audio، create-character، text-to-video
  • openai-tts: text-to-speech
  • fish-audio: text-to-speech
  • gemini-tts: text-to-speech
  • elevenlabs: isolate-audio، speech-to-text، text-to-dialogue، text-to-sound، text-to-speech

إجراءات الصورة

  • nano-banana: edit-image، text-to-image
  • imagen-4: remix-image، text-to-image
  • seedream: decompose-layers، edit-image، text-to-image
  • flux: remix-image، text-to-image
  • flux-2: remix-image، text-to-image
  • flux-kontext: text-to-image
  • qwen-2: edit-image، text-to-image
  • qwen-3: edit-image، text-to-image
  • qwen-image: edit-image، remix-image، text-to-image
  • recraft: remove-background، upscale-image
  • z-image: text-to-image
  • ideogram-v3: edit-image، reframe-image، remix-image، text-to-image
  • gpt-image: edit-image، text-to-image
  • gpt-image-2: edit-image، text-to-image
  • gpt-4o-image: text-to-image
  • midjourney: edit-image، get-seed، image-to-prompt، shorten-prompt، text-to-image

إجراءات الفيديو والرسوم المتحركة

  • veo-3-1: extend-video، text-to-video، upscale-video
  • seedance: text-to-video
  • runway: extend-video، text-to-video
  • runway-aleph: edit-video
  • kling: avatar، edit-video، extend-video، image-to-video، motion-control، text-to-video
  • infinitetalk: audio-to-video
  • omnihuman: audio-to-video، human-identification، subject-detection
  • wan: animate، edit-video، image-to-video، speech-to-video، text-to-image، text-to-video
  • luma: modify-video
  • hailuo: image-to-video، text-to-video
  • volcengine-lip-sync: lip-sync-video
  • happyhorse: edit-video، image-to-video، text-to-video
  • grok-imagine: edit-image، extend، image-to-video، text-to-image، text-to-video، upscale-image
  • topaz: upscale-image، upscale-video
  • midjourney: extend-video، image-to-video

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

دورة حياة المهمة

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

SHELL 
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s

الملفات

runapi files create يحتفظ بتدفق رابط تحميل الملف المؤقت. يُحمّل مساراً محلياً واحداً أو رابط URL بعيداً أو مصدر Base64 ويُعيد رابطاً ينتهي صلاحيته بعد ساعة واحدة.

SHELL 
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png

خيارا المصدر متعارضان. يطبع --url-only عنوان URL وحده؛ احذفه لاستقبال استجابة JSON الكاملة.

استخدم دورة حياة الملف الدائم عندما تحتاج إلى file_id ثابت بدلاً من رابط URL:

SHELL 
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123

content يتطلب --output؛ مرّر - لكتابة بايتات الملف الدقيقة إلى الإخراج القياسي. راجع Files and Uploads للاطلاع على الحدود وعزل الحساب ودورة حياة REST.

الرفوعات

استخدم Uploads لإرسال جزء واحد أو أكثر من Parts قبل تأليف الملف النهائي File. تُعلن Create عن عدد البايتات النهائي والبيانات الوصفية؛ كرر --part-id بترتيب التأليف عند الاكتمال:

SHELL 
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123

الحساب والتسعير

افحص المستخدم المُصادق عليه والحساب المحدد، ثم استعلم عن الرصيد وعدادات الإنفاق:

SHELL 
runapi account info
runapi account balance

pricing list يقرأ جداول الأسعار الحالية. صفّه حسب الخدمة أو الإجراء أو النموذج. يُقدّر pricing quote حجز المهمة لخدمة وإجراء محددَين؛ أضف --model عندما يكون الإجراء خاصاً بنموذج معين وزوّد مدخلات التسعير باستخدام --params أو --params-file.

SHELL 
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
  --params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json

لا تتطلب أوامر التسعير بيانات اعتماد إلا إذا كان العرض يشير إلى مهمة مصدر مملوكة لحساب.

المصادقة والإعداد

runapi login يفتح تدفق تفويض المتصفح ويحفظ بيانات الاعتماد الناتجة. للخوادم وبيئات CI، يقبل auth import-token مفتاح API من المدخل القياسي ويتحقق منه افتراضياً ويحفظه دون إظهار القيمة في قائمة العمليات أو سجل الشل:

SHELL 
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout

auth import-token --skip-verify يدعم إعداد الصورة دون اتصال. استخدمه فقط عندما لا يمكن تشغيل التحقق أثناء الإعداد؛ يتحقق auth status من بيانات الاعتماد النشطة لاحقاً.

أولوية مفتاح API هي --api-key، ثم RUNAPI_API_KEY، ثم ملف تكوين CLI المحلي. أولوية Base URL هي --base-url، ثم RUNAPI_BASE_URL، ثم Base URL المحفوظ، ثم https://runapi.ai. ملف التكوين هو ~/.config/runapi/config.json، أو $XDG_CONFIG_HOME/runapi/config.json حين يكون XDG_CONFIG_HOME مضبوطاً.

مستمع عمليات الاستدعاء المحلي

runapi listen يستقبل عمليات استدعاء المهام لمفتاح API واحد محدد ويُعيد توجيه كل استدعاء موقّع اختيارياً إلى نقطة نهاية HTTP محلية. يُشترط تسجيل الدخول عبر المتصفح قبل استخدام عمليات الاستماع.

SHELL 
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123

عنوان URL الموضعي و--forward-to بديلان لبعضهما. يكتب المستمع كل جسم استدعاء موقَّع إلى الإخراج القياسي. تستمر مهمة تحتوي على callback_url في التسليم إلى عنوان URL ذاك وتُنسَخ أيضًا إلى المستمع المحلي.

بعد تلقي حدث مستمع صالح، يُقرّ CLI باستلامه قبل محاولة طلب HTTP المحلي. يُوجَّه كل حدث محلياً مرة واحدة: تُبلَّغ الاستجابات غير 2xx وأخطاء الاتصال في الطرفية، لكنها لا تجعل المستمع يُعيد إرسال الحدث. لا يؤثر هذا السلوك في تصحيح الأخطاء المحلي على إعادة محاولات تسليم callback_url الخاصة بالمهمة.

يمكن لكل حساب تشغيل ما يصل إلى 100 مستمع نشط لكل مفتاح اشتراك Callback و1,000 مستمع نشط إجمالاً. عند الوصول إلى الحد، أوقف مستمعاً خاملاً أو انتظر وأعد المحاولة. يحدد رد API ما إذا كان المفتاح المحدد أو حسابك أو طاقة الخدمة الكلية قد امتلأت.

يتحقق المستمع الخامل من الأحداث الجديدة كل 15 إلى 30 ثانية تقريباً. تُكتشف الأحداث عادةً في غضون نحو 15 ثانية وتُقرأ فور توفرها. عند بلوغ حد معين، أوقف مستمعاً خاملاً أو انتظر وحاول مجدداً. يظل سلوك التسليم والإقرار الحالي دون تغيير.

ترتيب اختيار المفتاح هو: --callback-api-key-id لأمر واحد، ثم callback_api_key_id في .runapi.toml الخاص بالمشروع، ثم محدد تفاعلي. يُحفظ إعداد المشروع في جذر Git، أو الدليل الحالي خارج مستودع Git، ويحتوي فقط على المعرّف الثابت:

TOML 
callback_api_key_id = "token_abc123"

اطبع سرّ التوقيع الخاص بمفتاح مُحدد دون بدء مستمع، أو أعِد تدويره بعد تعرّضه:

SHELL 
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123

يُبطل التدوير المستمعين النشطين للمفتاح المحدد. حدِّث كل مُتحقِّق محلي بالسرّ المطبوع حديثاً قبل إعادة تشغيل مستمعه.

Harness

ثبّت مهارة RunAPI CLI المحمولة في Harness مدعوم، افحص الأهداف المدعومة، أو أزل مهارة مثبتة:

SHELL 
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex

الأهداف المدمجة هي claude وcodex وgemini وopenclaw و hermes. يقبل install-skill الخيار --version لتثبيت إصدار مهارة، و--target-dir لمسار وجهة مخصص، و--source لمستودع مصدر، و--force للكتابة فوق دليل مهارة موجود.

إكمال الصدفة والإصدار

أنشئ سكريبتات الإكمال التلقائي لـ Bash أو Zsh أو Fish أو PowerShell. على سبيل المثال، لتحميل إكمال Bash في الصدفة الحالية:

SHELL 
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version

استخدم runapi --help لعرض قائمة الأوامر، وrunapi <command> --help لخيارات أمر معين، وrunapi <service> <action> --help لحقول إجراء نموذج معين.

رموز الخروج

تخرج الأوامر برمز غير صفري يمكن للنصوص البرمجية التعامل معه:

الرمز المعنى 0 نجاح 2 فشل المصادقة أو منصة غير مدعومة 3 رصيد غير كافٍ أو تبعية محلية مطلوبة مفقودة 4 خطأ في التحقق أو العنصر غير موجود أو خطأ في تحليل البيان 5 انتهاء المهلة أو فشل التنزيل أو عدم تطابق المجموع الاختباري 6 تجاوز حد المعدل 7 فشل المهمة

للاطلاع على حقول الطلب وقيم حالة المهمة وحمولات عمليات الاستدعاء وأجسام الأخطاء ومعالجة حدود المعدل، تابع مع مرجع API . استخدم SDKs عندما ينتمي نفس سير العمل داخل تطبيق.