Quickstart - Runbase Docs

Not ready to write code yet? Try the Playground — test any model directly in your browser, no API key needed.

1. Create an account

2. Get an API key

Go to Settings → API Keys and create a new key. Copy it somewhere safe — it starts with sk- and won't be shown again.

export RUNBASE_API_KEY="sk-your-key-here"

3. Create a run

Send a POST to /api/v1/runs with a model ID and input parameters:

curl -s https://runbase.net/api/v1/runs \
  -H "Authorization: Bearer $RUNBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-2",
    "input": {
      "prompt": "A cozy bookshop interior with warm lighting, watercolor style",
      "aspect_ratio": "1:1"
    }
  }'

Response:

{
  "id": "run_2abc...",
  "model": "google/nano-banana-2",
  "status": "pending",
  "costUsd": 40000
}

The costUsd is in micro-USD (1 USD = 1,000,000). A cost of 40,000 means $0.04.

4. Poll for the result

Use the run ID to check status:

curl -s https://runbase.net/api/v1/runs/run_2abc... \
  -H "Authorization: Bearer $RUNBASE_API_KEY"

When status is "succeeded", the output field contains the result:

{
  "id": "run_2abc...",
  "status": "succeeded",
  "model": "google/nano-banana-2",
  "costUsd": 40000,
  "output": {
    "urls": [
      "https://runbase.net/files/generated/abc123.png"
    ]
  },
  "createdAt": "2026-06-01T12:00:00.000Z",
  "completedAt": "2026-06-01T12:00:04.200Z"
}

If a run fails, status will be "failed" and the cost is automatically refunded to your balance.

5. Download the image

The URLs in the output are direct links to the generated images or videos. They're served from a global CDN and available immediately.

What's next

Core Concepts — understand run lifecycle, async model, and cost mechanics
Authentication — set up IP whitelisting and spend limits for production
Models — explore all available models and try them in the playground
Billing — top up and manage your balance