Zasoby dla deweloperów

CLI

Zainstaluj i używaj wszystkich poleceń CLI RunAPI do akcji modelu, zadań, plików, przesyłania, informacji o koncie, cennika, wywołań zwrotnych i Harness.

Zobacz Markdown

RunAPI CLI to terminalowy klient stawiający JSON na pierwszym miejscu, przeznaczony do działań na modelach i zarządzania kontem. Zapisuje dane wyników na standardowe wyjście, a postęp operacyjny na standardowe wyjście błędów, dzięki czemu działa równie dobrze w terminalu, skryptach powłoki, zadaniach CI i środowisku Harness.

Instalacja

Zainstaluj bieżącą wersję w systemie Linux lub macOS:

SHELL

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

Dostępne są również instalacje przez Homebrew i ze źródła Go:

SHELL

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

W systemie Windows pobierz odpowiednie archiwum windows-amd64 lub windows-arm64 z najnowszego wydania CLI, wyodrębnij plik runapi.exe i dodaj go do zmiennej PATH.

Przypnij instalator do określonej wersji lub katalogu instalacyjnego, gdy wdrożenie wymaga odtwarzalnego pliku binarnego:

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"

Instalator akceptuje również zmienne RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE i RUNAPI_SKIP_LIBC_CHECK=1.

Szybki start

Na stacji roboczej zaloguj się w przeglądarce i potwierdź źródło poświadczeń:

SHELL

runapi login
runapi auth status

Uruchom akcję modelu z wbudowanym wejściem JSON lub plikiem 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

Większość akcji modelu jest asynchroniczna. Domyślnie oczekują na wynik końcowy; dodaj --async, aby natychmiast zwrócić zadanie i użyć wait później:

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

Konwencje poleceń

Każde polecenie wyświetla JSON na standardowym wyjściu, chyba że opcja jawnie żąda wartości skalarnej, np. files create --url-only lub listen --print-secret. Komunikaty postępu i diagnostyczne trafiają na standardowe wyjście błędów, dzięki czemu JSON może bezpiecznie być przekazywany do jq:

SHELL

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

Akcje modelu przyjmują dokładnie jedno źródło danych wejściowych żądania:

--input '<json object>' dostarcza JSON bezpośrednio w wierszu polecenia.
--input-file path/to/request.json wczytuje JSON z pliku.
--input-file - odczytuje JSON ze standardowego wejścia.

Użyj runapi <service> <action> --help przed skonstruowaniem żądania. Zainstalowany CLI wyświetla aktualne pola akcji, akceptowane identyfikatory modeli oraz ograniczenia walidacji.

Te opcje globalne dotyczą każdego polecenia:

Opcja Przeznaczenie --api-key Użyj klucza API dla tego wywołania. Zastępuje RUNAPI_API_KEY. --base-url Użyj innego źródła API dla tego wywołania. --timeout Ustaw ogólny limit czasu polecenia oraz maksymalny czas oczekiwania na zadanie. Domyślnie wynosi 15 minut. --poll-interval Ustaw interwał odpytywania zadań. Domyślnie wynosi 3 sekundy. --async Zwróć odpowiedź natychmiast po przesłaniu asynchronicznego działania modelu. --quiet Wyłącz wyświetlanie postępu na standardowym wyjściu błędów bez zmiany wyjścia JSON.

Akcje modelu

Składnia polecenia modelu to runapi <service> <action>. Akcje synchroniczne zwracają odpowiedź natychmiast. W przypadku akcji asynchronicznych domyślne zachowanie polega na przesłaniu, odpytywaniu i zwróceniu końcowego wyniku zadania; --async zwraca zamiast tego odpowiedź tworzenia.

W przypadku pól adresów URL multimediów najwyższego poziomu lokalny plik z możliwością odczytu jest przesyłany przed wykonaniem akcji modelu. Istniejące adresy URL http:// i https:// są wysyłane bez zmian. Używaj files create, gdy potrzebujesz wielokrotnego użytku tymczasowego adresu URL, gdy źródłem jest zdalny adres URL lub gdy źródłem są dane Base64.

Akcje dotyczące dźwięku i muzyki

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

Akcje na obrazach

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

Akcje dotyczące wideo i animacji

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

Powyższa lista stanowi kompletny inwentarz akcji w tej wersji CLI. Dokładny kontrakt żądania i odpowiedzi każdej akcji jest dostępny w Dokumentacji interfejsu API, a lokalna pomoc polecenia jest źródłem pól specyficznych dla danej wersji.

Cykl życia zadania

Użyj get, aby sprawdzić bieżący stan asynchronicznego Zadania (Task) bez oczekiwania. Użyj wait, aby odpytywać aż do jego zakończenia, niepowodzenia lub upływu limitu czasu polecenia. Oba polecenia wymagają podania oryginalnej usługi i akcji, aby CLI mógł wybrać właściwy kształt wyniku Zadania (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

Pliki (Files)

runapi files create zachowuje tymczasowy przepływ z adresem URL przesyłania pliku. Przesyła jedną lokalną ścieżkę, zdalny adres URL lub źródło Base64 i zwraca adres URL, który wygasa po jednej godzinie.

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

Opcje źródła wzajemnie się wykluczają. --url-only wyświetla wyłącznie URL; pomiń tę opcję, aby otrzymać pełną odpowiedź JSON.

Użyj trwałego cyklu życia pliku, gdy potrzebujesz stabilnego file_id zamiast adresu 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 wymaga --output; podaj -, aby zapisać dokładne bajty pliku File na standardowe wyjście. Zobacz Pliki i przesyłanie, aby zapoznać się z limitami, izolacją konta i cyklem życia REST.

Przesyłanie plików

Użyj Uploads, aby wysłać jedną lub więcej Parts przed złożeniem ostatecznego pliku File. Create deklaruje końcową liczbę bajtów i metadane; podczas finalizowania powtarzaj --part-id w kolejności składania:

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

Konto i cennik

Sprawdź uwierzytelnionego użytkownika i wybrany rachunek, a następnie pobierz saldo i liczniki wydatków:

SHELL

runapi account info
runapi account balance

pricing list odczytuje aktualne cenniki. Filtruj według usługi, akcji lub modelu. pricing quote szacuje rezerwację Task dla wymaganej usługi i akcji; dodaj --model, gdy akcja jest specyficzna dla modelu, i podaj dane wejściowe do wyceny za pomocą --params lub --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

Polecenia dotyczące cen nie wymagają poświadczeń, chyba że wycena dotyczy zadania źródłowego należącego do konta.

Uwierzytelnianie i konfiguracja

runapi login otwiera przepływ autoryzacji w przeglądarce i zapisuje uzyskane poświadczenie. W przypadku serwerów i CI auth import-token przyjmuje klucz API ze standardowego wejścia, domyślnie go weryfikuje i zapisuje bez ujawniania wartości na liście procesów ani w historii powłoki:

SHELL

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

auth import-token --skip-verify obsługuje konfigurację obrazu w trybie offline. Używaj tej opcji tylko wtedy, gdy weryfikacja nie może zostać przeprowadzona podczas konfiguracji; auth status weryfikuje aktywne poświadczenie później.

Pierwszeństwo klucza API: --api-key, następnie RUNAPI_API_KEY, następnie lokalna konfiguracja CLI. Pierwszeństwo base URL: --base-url, następnie RUNAPI_BASE_URL, następnie zapisany base URL, następnie https://runapi.ai. Plik konfiguracyjny to ~/.config/runapi/config.json lub $XDG_CONFIG_HOME/runapi/config.json, gdy XDG_CONFIG_HOME jest ustawione.

Lokalny odbiornik wywołań zwrotnych

runapi listen odbiera wywołania zwrotne Task dla jednego wybranego klucza API i opcjonalnie przekazuje każde podpisane wywołanie zwrotne do lokalnego punktu końcowego HTTP. Przed skorzystaniem z operacji nasłuchiwania wymagane jest logowanie przez przeglądarkę.

SHELL

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

Pozycyjny URL i --forward-to są alternatywami. Odbiornik zapisuje każde podpisane ciało wywołania zwrotnego na standardowe wyjście. Zadanie z callback_url nadal dostarcza dane pod ten URL, a kopie są również przesyłane do lokalnego odbiornika.

Po otrzymaniu prawidłowego zdarzenia przez listener CLI potwierdza je przed podjęciem lokalnego żądania HTTP. Każde zdarzenie jest przekazywane lokalnie jednorazowo: odpowiedzi inne niż 2xx oraz błędy połączenia są zgłaszane w terminalu, ale nie powodują ponownego odtworzenia zdarzenia przez listener. To lokalne zachowanie debugowania nie wpływa na ponowne próby dostarczenia dla callback_url zadania (Task).

Każde konto może prowadzić do 100 aktywnych odbiorników na klucz subskrypcji wywołań zwrotnych (Callback Subscription Key) i łącznie 1000 aktywnych odbiorników. Po osiągnięciu limitu zatrzymaj bezczynny odbiornik lub poczekaj i spróbuj ponownie. Odpowiedź API informuje, czy limit osiągnął wybrany klucz, Twoje konto czy ogólna pojemność usługi.

Bezczynny listener sprawdza nowe zdarzenia mniej więcej co 15–30 sekund. Zdarzenia są zwykle wykrywane w ciągu około 15 sekund i odczytywane natychmiast po ich dostępności. W przypadku osiągnięcia limitu zatrzymaj bezczynny listener lub poczekaj i spróbuj ponownie. Istniejące zachowanie dostarczania i potwierdzania pozostaje niezmienione.

Kolejność wyboru klucza: --callback-api-key-id dla jednego polecenia, callback_api_key_id w projekcie .runapi.toml, a następnie interaktywny selektor. Konfiguracja projektu jest zapisywana w katalogu głównym Git lub bieżącym katalogu poza repozytorium Git i zawiera tylko stabilne ID:

TOML

callback_api_key_id = "token_abc123"

Wydrukuj sekret podpisywania nasłuchiwania wybranego klucza bez uruchamiania nasłuchiwania lub obróć go po ujawnieniu:

SHELL

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

Rotacja unieważnia aktywnych odbiorców dla wybranego klucza. Zaktualizuj każdy lokalny weryfikator nowo wygenerowanym sekretem przed ponownym uruchomieniem jego odbiorcy.

Harness

Zainstaluj przenośną umiejętność CLI RunAPI w obsługiwanym Harness, sprawdź obsługiwane cele lub usuń zainstalowaną umiejętność:

SHELL

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

Wbudowane cele to claude, codex, gemini, openclaw i hermes. Polecenie install-skill przyjmuje --version do przypięcia wersji umiejętności, --target-dir dla niestandardowego katalogu docelowego, --source dla repozytorium źródłowego oraz --force do nadpisania istniejącego katalogu umiejętności.

Uzupełnianie powłoki i wersja

Generuj skrypty uzupełniania dla Bash, Zsh, Fish lub PowerShell. Na przykład załaduj uzupełnianie Bash w bieżącej powłoce:

SHELL

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

Użyj runapi --help, aby wyświetlić listę poleceń, runapi <command> --help w celu poznania opcji danego polecenia, a runapi <service> <action> --help w celu poznania pól akcji modelu.

Kody wyjścia

Polecenia kończą się niezerowym kodem, który skrypty mogą obsłużyć:

Kod Znaczenie 0 Sukces 2 Błąd uwierzytelniania lub nieobsługiwana platforma 3 Niewystarczające środki lub brakująca wymagana zależność lokalna 4 Błąd walidacji, brak zasobu lub błąd parsowania manifestu 5 Przekroczenie limitu czasu, błąd pobierania lub niezgodność sumy kontrolnej 6 Przekroczono limit żądań 7 Zadanie zakończone niepowodzeniem

W przypadku pól żądania, wartości statusu zadań, ładunków wywołań zwrotnych, treści błędów i obsługi limitów szybkości przejdź do Dokumentacji interfejsu API. Używaj SDK, gdy ten sam przepływ pracy należy do aplikacji.