# AI images (Imagine) API

> KickBot API and MCP reference for AI images: the !imagine command settings, its on-stream widget, test images and the image queue.

Source: https://kickbot.com/docs/api/reference/imagine

Use these actions to set up the `!imagine` command, which makes an AI image from a viewer prompt and shows it on stream.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `imagine`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=imagine`.

A team member needs the **Imagine** permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [AI images](https://kickbot.com/docs/ai/ai-images).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`get_imagine_settings`](#get_imagine_settings) | `GET /imagine/settings` | Read |
| [`update_imagine_settings`](#update_imagine_settings) | `PATCH /imagine/settings` | Write |
| [`test_imagine`](#test_imagine) | `POST /imagine/test` | Write |
| [`get_imagine_queue`](#get_imagine_queue) | `GET /imagine/queue` | Read |

## get_imagine_settings

**Get the AI image (Imagine) settings.** Read the !imagine settings: on/off, who can use it, the on-stream widget options, the widget URL (add it as a browser source in OBS), and images used in the last 30 days against the plan limit.

```http
GET /api/v1/imagine/settings
```

No input fields.

## update_imagine_settings

**Update the AI image (Imagine) settings.** Change some !imagine settings. Only the fields you send change. Requires a verified account.

```http
PATCH /api/v1/imagine/settings
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | No | Turn the !imagine chat command on or off. |
| `everyone_only` | boolean | No | Everyone in chat can use it. |
| `subscriber_only` | boolean | No | Subscribers can use it (when everyone_only is false). |
| `vip_only` | boolean | No | VIPs can use it (when everyone_only is false). |
| `mod_only` | boolean | No | Moderators can use it (when everyone_only is false). |
| `show_command` | boolean | No | Show the viewer name and prompt under the image on the widget. Default true. |
| `url_response` | boolean | No | Reply in chat with a link to the image. Default true. |
| `on_screen_time` | integer | No | Seconds each image stays on the widget, 5-300. Default 60. |
| `slide_direction` | string | No | How images appear on the widget: none, fade, left, right, bottom, top. Default bottom. |
| `style` | `"none"` or `"anime"` or `"film"` or `"cartoon"` or `"bricks"` or `"animated_3d"` or `"clay"` or `"pixel"` or `"comic"` or `"photo"` or `"watercolor"` or `"oil"` or `"neon"` | No | Image style guideline added to every prompt: none, anime, film, cartoon, bricks, animated_3d, clay, pixel, comic, photo, watercolor, oil, neon. "none" uses the prompt as written. Premium only (Free channels always use none). Default none. |

## test_imagine

**Show a test image on the Imagine widget.** Show a sample image on the Imagine widget so the streamer can check the overlay in OBS. It appears on the live stream if the widget is in the scene. Test images do not count against the limit.

```http
POST /api/v1/imagine/test
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 20 per minute.

No input fields.

## get_imagine_queue

**Get recent AI images.** List the images made in the last few minutes, oldest first. With the default of 1 minute this is what the widget is showing or about to show.

```http
GET /api/v1/imagine/queue
```

| Field | Type | Required | Description |
|---|---|---|---|
| `minutes` (query) | integer | No | How many minutes back to look (1-1440, default 1). |