Runs
run은 단일 생성 요청입니다. API를 호출하면 Runbase가 run을 생성하여 기본 AI 모델로 전송하고, 준비되면 결과를 반환합니다.
각 run은 다음 생명주기를 거칩니다:
POST /api/v1/runs → pending → processing → succeeded (or failed)
Run 상태
| 상태 | 의미 |
|---|---|
pending | 대기 중이며, 작업자가 가져가기를 기다리는 상태 |
processing | AI 제공업체에서 활성 생성 중 |
succeeded | 생성 완료 — output.urls에 결과가 포함됨 |
failed | 생성 실패 — error에 무엇이 잘못되었는지 설명됨 |
설계상 비동기
모든 생성은 비동기입니다. run을 생성하면 API는 status: "pending"와 run ID를 반환하며 즉시 응답합니다. 그런 다음 상태가 succeeded 또는 failed이 될 때까지 GET /api/v1/runs/:id를 폴링합니다.
처리 시간은 모델, 제공업체 부하, 입력 복잡도에 따라 달라집니다:
- 이미지 모델은 보통 비디오 모델보다 더 빨리 완료됩니다
- 비디오 모델은 지속 시간, 해상도, 제공업체 큐 시간에 크게 좌우됩니다
비용 및 환불
비용은 run이 완료될 때가 아니라 run이 생성될 때 잔액에서 차감됩니다. 이는 자금을 선결제 방식으로 예약하는 것입니다.
run이 실패하면 전체 비용이 잔액으로 자동 환불됩니다. 실패한 생성에 대해서는 비용을 지불하지 않습니다.
Models
Runbase는 여러 제공업체의 모델을 위한 통합 게이트웨이입니다. 각 모델은 provider/model-name 형식의 고유 ID를 가집니다(예: openai/gpt-image-2, bytedance/seedance-2).
모든 모델은 동일한 두 엔드포인트 API를 공유합니다:
POST /api/v1/runs— 모델 ID와 입력으로 run 생성GET /api/v1/runs/:id— 상태 확인 및 결과 가져오기
입력 스키마는 모델마다 다르지만(prompt, size, quality, image_urls 등 다양한 매개변수), 요청/응답 래퍼는 항상 동일합니다.
인증
모든 API 요청에는 Authorization 헤더에 Bearer token 형태의 API 키가 필요합니다. 키는 sk-로 시작하며 대시보드에서 생성할 수 있습니다. 자세한 내용은 Authentication을 참조하세요.
Balance
Runbase는 선불 잔액을 사용합니다. 잔액을 top up하면 각 run이 모델의 가격 책정에 따라 그 잔액에서 차감됩니다. 자세한 내용은 Billing을 참조하세요.