CLI
Model eylemleri, Görevler, Dosyalar, Yüklemeler, hesap bilgileri, fiyatlandırma, geri çağırmalar ve Harness için her RunAPI CLI komutunu yükleyin ve kullanın.
RunAPI CLI, model eylemleri ve hesap araçları için JSON öncelikli bir terminal istemcisidir. Sonuç verilerini standart çıktıya, operasyonel ilerlemeyi ise standart hataya yazar; bu sayede terminal, kabuk betikleri, CI işleri ve Harness ortamlarında eşit biçimde çalışır.
Yükle
Linux veya macOS’ta mevcut sürümü yükleyin:
curl -fsSL https://runapi.ai/cli/install.sh | sh
Homebrew ve Go kaynak kurulumları da mevcuttur:
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
Windows’ta, en son CLI sürümünden uygun windows-amd64 veya windows-arm64 arşivini indirin, runapi.exe dosyasını çıkarın ve PATH‘e ekleyin.
Yeniden üretilebilir bir ikili dosya gerektiren bir dağıtımda yükleyiciyi belirli bir sürüme veya kurulum dizinine sabitlemek için:
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"
Yükleyici ayrıca RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE ve RUNAPI_SKIP_LIBC_CHECK=1 değişkenlerini de kabul eder.
Hızlı başlangıç
Bir iş istasyonunda tarayıcıda oturum açın ve kimlik bilgisi kaynağını doğrulayın:
runapi login
runapi auth status
Satır içi JSON girişiyle veya bir JSON dosyasıyla bir model eylemi çalıştırın:
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
Model eylemlerinin çoğu eşzamansızdır. Varsayılan olarak terminal sonucu beklerler; Görevi hemen döndürmek ve daha sonra wait kullanmak için --async ekleyin:
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
Komut kuralları
Her komut, bir seçenek açıkça skalar değer talep etmediği sürece standart çıktıya JSON yayar; örneğin files create --url-only veya listen
--print-secret. İlerleme ve tanı iletileri standart hatada kalır; böylece JSON güvenle jq‘ya yönlendirilebilir:
runapi nano-banana text-to-image --input-file request.json \
| jq -r '.images[].url' \
| xargs -I{} curl -OL {}
Model eylemleri tam olarak bir istek girdi kaynağını kabul eder:
--input '<json object>'satır içi JSON sağlar.--input-file path/to/request.jsonbir dosyadan JSON yükler.--input-file -standart girdiden JSON okur.
İstek oluşturmadan önce runapi <service> <action> --help komutunu kullanın. Kurulu CLI, eylemin mevcut alanlarını, kabul edilen model tanımlayıcılarını ve doğrulama kısıtlamalarını listeler.
Bu genel seçenekler her komut için geçerlidir:
--api-key
Bu çağrı için bir API anahtarı kullanır. RUNAPI_API_KEY değerini geçersiz kılar.
--base-url
Bu çağrı için farklı bir API kaynağı kullanır.
--timeout
Genel komut zaman aşımını ve maksimum Görev bekleme süresini ayarlar. Varsayılan değer 15 dakikadır.
--poll-interval
Görev yoklama aralığını ayarlar. Varsayılan değer 3 saniyedir.
--async
Eşzamansız bir model eylemi gönderildikten hemen sonra geri döner.
--quiet
JSON çıktısını değiştirmeden standart hata üzerindeki ilerleme bilgisini gizler.
Model eylemleri
Model komut biçimi runapi <service> <action> şeklindedir. Eş zamanlı eylemler yanıtı hemen döndürür. Eş zamansız eylemlerde varsayılan davranış gönder, yokla ve terminal Görev sonucunu döndür şeklindedir; --async ise bunun yerine oluşturma yanıtını döndürür.
Üst düzey medya URL alanları için, model eylemi çalışmadan önce okunabilir bir yerel dosya yolu yüklenir. Mevcut http:// ve https:// URL’leri değiştirilmeden gönderilir. Yeniden kullanılabilir geçici bir URL’ye ihtiyaç duyduğunuzda, kaynak uzak bir URL olduğunda veya kaynak Base64 verisi olduğunda files create komutunu kullanın.
Ses ve müzik işlemleri
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-phraseproducer:text-to-musicgemini-omni:create-audio,create-character,text-to-videoopenai-tts:text-to-speechfish-audio:text-to-speechgemini-tts:text-to-speechelevenlabs:isolate-audio,speech-to-text,text-to-dialogue,text-to-sound,text-to-speech
Görüntü eylemleri
nano-banana:edit-image,text-to-imageimagen-4:remix-image,text-to-imageseedream:decompose-layers,edit-image,text-to-imageflux:remix-image,text-to-imageflux-2:remix-image,text-to-imageflux-kontext:text-to-imageqwen-2:edit-image,text-to-imageqwen-3:edit-image,text-to-imageqwen-image:edit-image,remix-image,text-to-imagerecraft:remove-background,upscale-imagez-image:text-to-imageideogram-v3:edit-image,reframe-image,remix-image,text-to-imagegpt-image:edit-image,text-to-imagegpt-image-2:edit-image,text-to-imagegpt-4o-image:text-to-imagemidjourney:edit-image,get-seed,image-to-prompt,shorten-prompt,text-to-image
Video ve animasyon işlemleri
veo-3-1:extend-video,text-to-video,upscale-videoseedance:text-to-videorunway:extend-video,text-to-videorunway-aleph:edit-videokling:avatar,edit-video,extend-video,image-to-video,motion-control,text-to-videoinfinitetalk:audio-to-videoomnihuman:audio-to-video,human-identification,subject-detectionwan:animate,edit-video,image-to-video,speech-to-video,text-to-image,text-to-videoluma:modify-videohailuo:image-to-video,text-to-videovolcengine-lip-sync:lip-sync-videohappyhorse:edit-video,image-to-video,text-to-videogrok-imagine:edit-image,extend,image-to-video,text-to-image,text-to-video,upscale-imagetopaz:upscale-image,upscale-videomidjourney:extend-video,image-to-video
Yukarıdaki liste, bu CLI sürümündeki eksiksiz eylem envanterini içerir. Her eylemin kesin istek ve yanıt sözleşmesi API başvurusunda bulunabilir; yerel komut yardımı ise sürüme özgü alanlar için birincil kaynaktır.
Görev yaşam döngüsü
Beklemeden eş zamansız bir Görevin mevcut durumunu incelemek için get kullanın. Görev tamamlanana, başarısız olana veya komut zaman aşımına ulaşana kadar yoklamak için wait kullanın. Her iki komut da CLI’nin doğru Görev sonuç şeklini seçebilmesi için özgün servis ve eylemi gerektirir.
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
Dosyalar
runapi files create, geçici Dosya Yükleme URL’si akışını korur. Tek bir yerel yol, uzak URL veya Base64 kaynağı yükler ve bir saat sonra süresi dolan bir URL döndürür.
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
Kaynak seçenekleri birbirini dışlar. --url-only yalnızca URL’yi yazdırır; tam JSON yanıtını almak için bu seçeneği kullanmayın.
URL yerine kararlı bir file_id gerektiğinde kalıcı Dosya yaşam döngüsünü
kullanın:
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 gerektirir; tam File baytlarını standart çıktıya yazmak için - geçirin. Limitler, Hesap yalıtımı ve REST yaşam döngüsü için Dosyalar ve Yüklemeler bölümüne bakın.
Upload'lar
Son Dosyayı oluşturmadan önce bir veya daha fazla Parça göndermek için Yüklemeler’i kullanın.
Create, son bayt sayısını ve meta verileri bildirir; tamamlarken kompozisyon sırasına göre --part-id ifadesini tekrarlayın:
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
Hesap ve fiyatlandırma
Kimliği doğrulanmış kullanıcıyı ve seçili Hesabı inceleyin, ardından bakiye ve harcama sayaçlarını sorgulayın:
runapi account info
runapi account balance
pricing list, geçerli Fiyat Tarifelerini okur. Hizmete, eyleme veya modele göre filtreleyin. pricing quote, gerekli bir hizmet ve eylem için Görev rezervasyonunu tahmin eder; eylem modele özgüyse --model ekleyin ve --params veya --params-file ile Fiyatlandırma Girdilerini sağlayın.
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
Fiyatlandırma komutları, teklif Hesaba ait bir kaynak Göreve atıfta bulunmadığı sürece kimlik bilgisi gerektirmez.
Kimlik doğrulama ve yapılandırma
runapi login, bir tarayıcı yetkilendirme akışı başlatır ve elde edilen kimlik bilgisini kaydeder. Sunucular ve CI ortamları için auth import-token, standart girişten bir API anahtarı kabul eder, varsayılan olarak doğrular ve değeri işlem listesinde veya kabuk geçmişinde göstermeden kaydeder:
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
auth import-token --skip-verify, çevrimdışı görüntü kurulumunu destekler. Yalnızca kurulum sırasında doğrulama çalıştırılamadığında kullanın; auth status komutu etkin kimlik bilgisini daha sonra doğrular.
API anahtarı öncelik sırası: --api-key, ardından RUNAPI_API_KEY, ardından yerel CLI yapılandırma dosyası. Base URL öncelik sırası: --base-url, ardından RUNAPI_BASE_URL, ardından kaydedilen base URL, ardından https://runapi.ai. Yapılandırma dosyası ~/.config/runapi/config.json konumundadır; XDG_CONFIG_HOME ayarlandığında ise $XDG_CONFIG_HOME/runapi/config.json kullanılır.
Yerel geri çağırma dinleyicisi
runapi listen, seçili bir API anahtarı için Görev geri çağırmalarını alır ve isteğe bağlı olarak imzalanan her geri çağırmayı yerel bir HTTP uç noktasına iletir. Dinleyici işlemlerini kullanmadan önce tarayıcı girişi gereklidir.
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
Konumsal URL ile --forward-to birbirinin alternatifidir. Dinleyici, imzalı her geri çağırma gövdesini standart çıktıya yazar. callback_url içeren bir Görev, o URL’ye iletim yapmayı sürdürür ve aynı zamanda yerel dinleyiciye kopyalanır.
Geçerli bir dinleyici olayı aldıktan sonra CLI, yerel HTTP isteğini denemeden önce bunu onaylar. Her olay yerel olarak bir kez iletilir: 2xx dışındaki yanıtlar ve bağlantı hataları terminalde raporlanır, ancak dinleyicinin olayı yeniden oynatmasına neden olmaz. Bu yerel hata ayıklama davranışı, bir Görevin callback_url teslimat yeniden denemelerini etkilemez.
Her Hesap, Geri Çağırma Abonelik Anahtarı başına en fazla 100 aktif dinleyici ve toplamda 1.000 aktif dinleyici çalıştırabilir. Bir sınıra ulaşıldığında boştaki bir dinleyiciyi durdurun ya da bekleyip tekrar deneyin. API yanıtı, seçili anahtarın, Hesabınızın veya genel hizmet kapasitesinin dolu olup olmadığını belirtir.
Boşta bekleyen bir dinleyici yaklaşık her 15 ile 30 saniyede bir yeni olayları denetler. Olaylar genellikle yaklaşık 15 saniye içinde bulunur ve mevcut olduğunda hemen okunur. Bir sınıra ulaşılırsa boşta bekleyen dinleyiciyi durdurun veya bekleyip yeniden deneyin. Mevcut teslimat ve onay davranışı değişmez.
Anahtar seçim sırası şöyledir: tek bir komut için --callback-api-key-id, proje .runapi.toml dosyasındaki callback_api_key_id, ardından etkileşimli seçici. Proje yapılandırması Git kökünde veya bir Git deposu dışındaysa geçerli dizinde kaydedilir ve yalnızca kararlı kimliği içerir:
callback_api_key_id = "token_abc123"
Bir dinleyici başlatmadan seçili anahtarın Dinleme İmzalama Sırrını yazdırın ya da açığa çıkmanın ardından döndürün:
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
Rotasyon, seçili anahtar için etkin dinleyicileri geçersiz kılar. Dinleyiciyi yeniden başlatmadan önce yeni yazdırılan sırrı her yerel doğrulayıcıyla güncelleyin.
Çalışma Ortamı
Taşınabilir RunAPI CLI becerisini desteklenen bir Harness’a yükleyin, desteklenen hedefleri inceleyin veya yüklü bir beceriyi kaldırın:
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
Yerleşik hedefler claude, codex, gemini, openclaw ve hermes‘tir. install-skill, bir beceri sürümünü sabitlemek için --version, özel bir hedef için --target-dir, kaynak depo için --source ve mevcut bir beceri dizininin üzerine yazmak için --force seçeneklerini kabul eder.
Kabuk tamamlama ve sürüm
Bash, Zsh, Fish veya PowerShell için tamamlama betikleri oluşturun. Örneğin, mevcut kabukta Bash tamamlamayı etkinleştirmek için:
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
Komutları listelemek için runapi --help, bir komutun seçenekleri için runapi <command> --help, bir model eyleminin alanları için runapi <service> <action> --help kullanın.
Çıkış kodları
Komutlar, betiklerin işleyebileceği sıfırdan farklı bir kodla çıkar:
0
Başarılı
2
Kimlik doğrulama hatası veya desteklenmeyen platform
3
Yetersiz kredi veya gerekli bir yerel bağımlılık eksik
4
Doğrulama, bulunamadı veya manifest ayrıştırma hatası
5
Zaman aşımı, indirme hatası veya sağlama toplamı uyuşmazlığı
6
Hız sınırına ulaşıldı
7
Görev başarısız oldu
İstek alanları, Görev durumu değerleri, geri çağırma yükleri, hata gövdeleri ve hız sınırı işleme için API Başvurusu ile devam edin. Aynı iş akışı bir uygulama içinde yer aldığında SDK’ları kullanın.