babbleBrush

Generate and iteratively edit images. Supports storage, UI for manual editing, history, version branching, time travel, reference images, and multiple AI models and providers with your own API keys.

# babbleBrush

babbleBrush is a voice-first image editor. Humans can use it directly to edit, view, manage images and agents can use it alongside their human or on behalf of the user to do the same programatically.

The units of work are canvases and versions, you create or use an existing canvas and edit the image inside of it as a canvas version, ie, the image edit. You can also upload images in the canvas to edit them, to use as a reference, or mixing them in the edit.

Website - https://babblebrush.com

API index - https://babblebrush.com/api

- Users start with trial credits
- After trial credits are exhausted, platform access must be unlocked(one time payment) to manage API keys
- Check `platform_access_unlocked` in `GET /api/v1/me` to see if unlocked

**Important:**
- If you haven't added a key for a provider, edits with that provider will use credits
- Your API usage is billed directly by the provider (Google, xAI, etc.)
- Keys are encrypted and stored securely

## Skill URL

| File | URL |
|------|-----|
| `claude/SKILL.md` | `https://babblebrush.com/babblebrush/claude/SKILL.md` |
| `openclaw/SKILL.md` | `https://babblebrush.com/babblebrush/openclaw/SKILL.md` |


## Core Concepts

### Canvas

A **Canvas** is a workspace for image generation & editing.
A canvas contains multiple **Canvas versions** representing the edit history.
The latest completed canvas version is the current image of any given canvas. 


### Canvas version

A **canvas version** represents an image edit inside a canvas, it's the main unit of work. 
It contains information all the information about the eidt, like the prompt, image references uploaded(the limit depends on the model), the source canvas version the edit branched from, the status, etc




## Authentication

All requests require an API key sent in the Authorization header.

```bash
Authorization: Bearer bb_...
```

You can create API tokens from the settings page at `https://babblebrush.com/app/settings`.

Once you have the API key, store it locally and securely.


---

## API Reference

- https://babblebrush.com/api

---

## Endpoint Details

### Get current user

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/me"
```

Response:

```json
{
  "email": "user@example.com",
  "credits": 5,
  "platform_access_unlocked": false,
  "platform_access_unlocked_at": null,
  "canvases_count": 1,
  "created_at": "2026-02-27T14:27:41.281Z"
}
```

Info:

- `platform_access_unlocked` - Whether user has unlocked platform access (required for BYOK after trial)


### List provider models

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/provider-models"
```

Response:

```json
{
  "providers": [
    {
      "id": "gemini",
      "label": "Gemini",
      "models": [
        {
          "id": "gemini-2.5-flash-image",
          "name": "Flash 2.5 - Nano Banana",
          "description": "Quick image generation",
          "max_imgs_per_prompt": 3
        }
      ]
    }
  ]
}
```

Info:

  - `max_imgs_per_prompt` - Maximum images accepted in a single prompt

### List provider credentials

See which providers have API keys configured.

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/provider-credentials"
```

Response:

```json
{
  "credentials": [
    {
      "provider": "gemini",
      "created_at": "2025-10-11T10:00:00.000Z",
      "updated_at": "2025-10-11T10:00:00.000Z"
    }
  ]
}
```

### Add/update provider API key

```bash
curl -X POST \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "gemini", "api_key": "AIza..."}' \
  "https://babblebrush.com/api/v1/provider-credentials"
```

Valid providers: `gemini`, `xai`

Response:

```json
{
  "credential": {
    "provider": "gemini",
    "created_at": "2025-10-11T10:00:00.000Z",
    "updated_at": "2025-10-11T10:00:00.000Z"
  },
  "message": "API key saved for gemini"
}
```

### Remove provider API key

```bash
curl -X DELETE \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/provider-credentials/gemini"
```

Response:

```json
{
  "message": "API key removed for gemini"
}
```

### List canvases

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/canvases"
```

Response:

```json
{
  "canvases": [
    {
      "public_token": "01234567-89ab-cdef-0123-456789abcdef",
      "title": "My Logo Design",
      "default_model": "gemini/gemini-2.5-flash-image",
      "current_version_id": 105,
      "latest_version_number": 5,
      "current_version_image_url": "https://babblebrush.com/rails/active_storage/...",
      "is_latest_version_pending": false,
      "created_at": "2025-10-11T10:00:00.000Z",
      "updated_at": "2025-10-11T12:30:00.000Z"
    }
  ]
}
```

### Create canvas with image

```bash
# With file upload
curl -X POST \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -F "title=My New Canvas" \
  -F "image=@/path/to/image.png" \
  "https://babblebrush.com/api/v1/canvases"

# With base64 image
curl -X POST \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My New Canvas",
    "default_model": "gemini/gemini-2.5-flash-image",
    "image": "data:image/png;base64,iVBORw0KGgo..."
  }' \
  "https://babblebrush.com/api/v1/canvases"
```

Response:

```json
{
  "public_token": "01234567-89ab-cdef-0123-456789abcdef",
  "title": "My New Canvas",
  "default_model": "gemini/gemini-2.5-flash-image",
  "current_version_id": 201,
  "latest_version_number": 1,
  "current_version_image_url": "https://babblebrush.com/rails/active_storage/...",
  "is_latest_version_pending": false,
  "created_at": "2025-10-11T10:00:00.000Z",
  "updated_at": "2025-10-11T10:00:00.000Z",
  "versions": [
    {
      "id": 201,
      "canvas_id": 42,
      "version_number": 1,
      "status": "completed",
      "prompt": null,
      "model_identifier": "gemini/gemini-2.5-flash-image",
      "fail_reason": null,
      "source_version_id": null,
      "job_identifier": null,
      "metadata": {},
      "image_url": "https://babblebrush.com/rails/active_storage/...",
      "created_at": "2025-10-11T10:00:00.000Z",
      "updated_at": "2025-10-11T10:00:00.000Z"
    }
  ]
}
```

### Create blank canvas

```bash
curl -X POST \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Blank Canvas"}' \
  "https://babblebrush.com/api/v1/canvases/blank"
```

### Get canvas details

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/canvases/01234567-89ab-cdef-0123-456789abcdef"
```

`/api/v1/canvases/:id` expects the canvas `public_token`.

Response includes full canvas details with all versions.

### Update canvas

```bash
# Update title
curl -X PATCH \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title"}' \
  "https://babblebrush.com/api/v1/canvases/01234567-89ab-cdef-0123-456789abcdef"

# Change default model
curl -X PATCH \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_model": "gemini/gemini-3-pro-image-preview"}' \
  "https://babblebrush.com/api/v1/canvases/01234567-89ab-cdef-0123-456789abcdef"
```

### Delete canvas

```bash
curl -X DELETE \
  -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/canvases/01234567-89ab-cdef-0123-456789abcdef"
```

Response:

```json
{"ok": true}
```

### List versions of a canvas

```bash
curl -H "Authorization: Bearer $BABBLEBRUSH_API_KEY" \
  "https://babblebrush.com/api/v1/canvases/01234567-89ab-cdef-0123-456789abcdef/versions"
```

Response:

```json
{
  "versions": [
    {
      "id": 5,
      "version_number": 5,
      "status": "completed",
      "prompt": "add a sunset bac