본문으로 건너뛰기
개발자 리소스
개발자 리소스

CLI

모델 작업, Tasks, Files, Uploads, 계정 정보, 가격, 콜백 및 Harness를 위한 모든 RunAPI CLI 명령을 설치하고 사용합니다.

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에서는 최신 CLI 릴리스에서 해당하는 windows-amd64 또는 windows-arm64 아카이브를 다운로드하고, 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를 추가하면 Task를 즉시 반환하고 나중에 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

명령어 규칙

모든 명령은 옵션이 files create --url-only 또는 listen --print-secret과 같이 스칼라 값을 명시적으로 요청하지 않는 한 표준 출력에 JSON을 출력합니다. 진행 및 진단 메시지는 표준 오류에 남으므로 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>입니다. 동기 액션은 응답을 즉시 반환합니다. 비동기 액션의 경우 기본 동작은 제출, 폴링 후 터미널 Task 결과를 반환하는 것이며, --async는 생성 응답을 대신 반환합니다.

최상위 미디어 URL 필드의 경우, 읽을 수 있는 로컬 파일 경로는 모델 작업이 실행되기 전에 업로드됩니다. 기존 http:// 및 https:// URL은 변경 없이 전송됩니다. 재사용 가능한 임시 URL이 필요하거나, 소스가 원격 URL이거나, 소스가 Base64 데이터인 경우 files create를 사용하세요.

오디오 및 음악 작업

  • 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

위 목록은 이 CLI 릴리스의 완전한 액션 목록입니다. 각 액션의 정확한 요청 및 응답 계약은 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 흐름을 유지합니다. 로컬 경로, 원격 URL, 또는 Base64 소스 하나를 업로드하고 한 시간 후 만료되는 URL을 반환합니다.

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 응답을 받으려면 이를 생략하세요.

URL 대신 안정적인 file_id가 필요할 때 영구 File 라이프사이클을 사용하세요:

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이 필요합니다. -를 전달하면 정확한 File 바이트를 표준 출력에 씁니다. 제한 사항, 계정 격리, REST 수명 주기에 대해서는 파일 및 업로드를 참조하세요.

업로드

최종 File을 구성하기 전에 Uploads를 사용하여 하나 이상의 Part를 전송하세요. 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

계정 및 요금

인증된 사용자와 선택된 Account를 검사한 후 잔액 및 지출 카운터를 조회하세요:

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이 설정된 경우 $XDG_CONFIG_HOME/runapi/config.json입니다.

로컬 콜백 리스너

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이 있는 Task는 해당 URL로 계속 전달되며 로컬 리스너에도 복사됩니다.

유효한 리스너 이벤트를 수신한 후, CLI는 로컬 HTTP 요청을 시도하기 전에 이를 확인합니다. 각 이벤트는 로컬에서 한 번만 전달됩니다. 2xx가 아닌 응답이나 연결 오류는 터미널에 보고되지만, 리스너가 이벤트를 재전송하지는 않습니다. 이 로컬 디버깅 동작은 Task의 callback_url에 대한 전달 재시도에 영향을 주지 않습니다.

각 계정은 콜백 구독 키당 최대 100개의 활성 리스너와 총 1,000개의 활성 리스너를 실행할 수 있습니다. 한도에 도달하면 유휴 리스너를 중지하거나 잠시 후 다시 시도하세요. API 응답은 선택된 키, 계정, 또는 전체 서비스 용량이 가득 찼는지 여부를 알려줍니다.

유휴 리스너는 약 15~30초마다 새 이벤트를 확인합니다. 이벤트는 보통 약 15초 내에 발견되며, 사용 가능한 경우 즉시 읽힙니다. 제한에 도달하면 유휴 리스너를 중단하거나 잠시 기다렸다가 다시 시도하십시오. 기존의 전달 및 확인 동작은 변경되지 않습니다.

키 선택 순서는 다음과 같습니다. 단일 명령에 대해 --callback-api-key-id, 프로젝트 .runapi.toml의 callback_api_key_id, 그 다음 대화형 선택기. 프로젝트 구성은 Git 루트 또는 Git 저장소 외부의 현재 디렉터리에 저장되며 안정적인 ID만 포함합니다:

TOML 
callback_api_key_id = "token_abc123"

리스너를 시작하지 않고 선택한 키의 Listen 서명 시크릿을 출력하거나, 노출 후 교체합니다:

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

교체는 선택한 키의 활성 리스너를 무효화합니다. 리스너를 재시작하기 전에 새로 출력된 시크릿으로 모든 로컬 검증자를 업데이트하세요.

Harness

지원되는 Harness에 이식 가능한 RunAPI CLI 스킬을 설치하고, 지원되는 대상을 검사하거나, 설치된 스킬을 제거합니다:

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이 아닌 코드와 함께 종료됩니다:

코드 의미 0 성공 2 인증 실패 또는 지원하지 않는 플랫폼 3 크레딧 부족 또는 필수 로컬 의존성 누락 4 유효성 검사 오류, 리소스를 찾을 수 없음, 또는 매니페스트 파싱 오류 5 타임아웃, 다운로드 실패, 또는 체크섬 불일치 6 요청 횟수 초과(속도 제한) 7 작업 실패

요청 필드, Task 상태 값, 콜백 페이로드, 오류 본문, 속도 제한 처리에 대해서는 API 참조를 계속하세요. 동일한 워크플로가 애플리케이션 내부에 속하는 경우 SDK를 사용하세요.