Runs
run は 1 回の生成リクエストです。API を呼び出すと、Runbase は run を作成し、基盤となる AI モデルに送信し、準備ができ次第結果を返します。
すべての run はライフサイクルをたどります:
POST /api/v1/runs → pending → processing → succeeded (or failed)
Run statuses
| Status | Meaning |
|---|---|
pending | キューに入り、worker が取り出すのを待っている |
processing | AI プロバイダーで生成中 |
succeeded | 生成完了 — output.urls に結果が含まれる |
failed | 生成失敗 — error に問題の内容が記載される |
Async by design
すべての生成は非同期です。run を作成すると、API は status: "pending" と run ID を返してすぐに応答します。その後、ステータスが succeeded または failed になるまで GET /api/v1/runs/:id をポーリングします。
所要時間はモデル、プロバイダーの負荷、入力の複雑さによって変わります:
- 画像モデルは通常、動画モデルよりも速く完了します
- 動画モデルは、長さ、解像度、プロバイダーのキュー時間に大きく左右されます
Cost and refunds
コストは、run が完了したときではなく、run が作成されたときに balance から差し引かれます。これにより、資金が事前に確保されます。
run が失敗した場合、全額が balance に自動的に返金されます。失敗した生成に対して料金が発生することはありません。
Models
Runbase は、複数のプロバイダーのモデルへの統合ゲートウェイです。各モデルには provider/model-name 形式の一意な ID があります（例: openai/gpt-image-2、bytedance/seedance-2）。
すべてのモデルは同じ 2 エンドポイント API を共有します:
POST /api/v1/runs— model ID と input を指定して run を作成するGET /api/v1/runs/:id— status を確認し、結果を取得する
input schema はモデルごとに異なります（prompt、size、quality、image_urls などのパラメータが異なる）が、request/response wrapper は常に同じです。
Authentication
すべての API リクエストには、Bearer token として Authorization header に API key が必要です。key は sk- で始まり、dashboard で作成できます。詳細は Authentication を参照してください。
Balance
Runbase は前払い balance を使用します。balance を top up すると、各 run は model の pricing に基づいてそこから差し引かれます。詳細は Billing を参照してください。