Runs
A run is a single generation request. When you call the API, Runbase creates a run, sends it to the underlying AI model, and returns the result when it's ready.
Every run goes through a lifecycle:
POST /api/v1/runs → pending → processing → succeeded (or failed)
Run statuses
| Status | Meaning |
|---|---|
pending | Queued, waiting for a worker to pick it up |
processing | Actively generating at the AI provider |
succeeded | Generation complete — output.urls contains the result |
failed | Generation failed — error describes what went wrong |
Async by design
All generation is asynchronous. When you create a run, the API returns immediately with status: "pending" and a run ID. You then poll GET /api/v1/runs/:id until the status is succeeded or failed.
Turnaround varies by model, provider load, and input complexity:
- Image models usually complete faster than video models
- Video models depend heavily on duration, resolution, and provider queue time
Cost and refunds
Cost is deducted from your balance when the run is created, not when it completes. This reserves the funds upfront.
If the run fails, the full cost is automatically refunded to your balance. You never pay for failed generations.
Models
Runbase is a unified gateway to models from multiple providers. Each model has a unique ID in the format provider/model-name (e.g., openai/gpt-image-2, bytedance/seedance-2).
All models share the same two-endpoint API:
POST /api/v1/runs— create a run with a model ID and inputGET /api/v1/runs/:id— check status and retrieve results
The input schema varies per model (different parameters for prompt, size, quality, image_urls, etc.), but the request/response wrapper is always the same.
Authentication
Every API request requires an API key in the Authorization header as a Bearer token. Keys start with sk- and can be created in the dashboard. See Authentication for details.
Balance
Runbase uses prepaid balance. You top up your balance, and each run deducts from it based on the model's pricing. See Billing for details.