---
title: "ring-image-create"
description: "MCP tool reference — generate images via ImageConductor (xAI Grok Imagine or Google Imagen) and store in ring-filebase"
locale: "en"
---
# `ring-image-create`

Generate an image from a natural-language prompt, upload it to **ring-filebase**, persist an audit row in `generated_images`, and return a permanent CDN URL.

Operators and agents call **`ring-image-create`** through `ring-mcp`. The gateway hits `POST /api/mcp/v1/images/generate`, which runs **`ImageConductor`** (`lib/images/conductor/image-conductor.ts`) with the MCP service actor as `actorId`. Default provider is **xAI** (`IMAGE_GEN_PROVIDER=xai`).

  
- **[MCP tools hub](/docs/mcp.md)** — Ring MCP overview, kingdom vs clone scope, prerequisites.

  
- **[Generative images (ImageConductor)](/docs/development/generative-images.md)** — Architecture, admin UI, programmatic API, troubleshooting.

  
- **[Ring MCP Server](/docs/development/ring-mcp.md)** — Token setup, `ring-health`, full tool catalog.

  
- **[Environment](/docs/deployment/environment.md)** — Image and storage env vars on the clone.

```mermaid
sequenceDiagram
  participant Agent as MCP host
  participant Mcp as ring-mcp
  participant GW as /api/mcp/v1/images/generate
  participant IC as ImageConductor
  participant Prov as xAI or Google
  participant FB as ring-filebase

  Agent->>Mcp: ring-image-create prompt
  Mcp->>GW: Bearer token + JSON body
  GW->>IC: generate(actorId)
  IC->>Prov: provider API
  Prov-->>IC: image buffer
  IC->>FB: file().upload
  IC-->>GW: url + recordId
  GW-->>Mcp: success + data
  Mcp-->>Agent: CDN URL
```

## Tool identity

| Field | Value |
|-------|--------|
| **MCP tool name** | `ring-image-create` |
| **HTTP route** | `POST /api/mcp/v1/images/generate` |
| **MCP server** | `AI-RING/ring-mcp/lib/tools.js` |
| **Gateway handler** | `app/api/mcp/v1/images/generate/route.ts` |
| **Conductor** | `lib/images/conductor/image-conductor.ts` |
| **Confirm required** | No (read-only generation + storage) |

## Parameters

| Parameter | Required | Type | Notes |
|-----------|----------|------|-------|
| `prompt` | **Yes** | string | Natural-language image description |
| `provider` | No | `xai` \| `google` | Default from `IMAGE_GEN_PROVIDER` (usually `xai`) |
| `model` | No | string | Override provider model (see env defaults below) |
| `aspectRatio` | No | string | xAI: flexible; Google: `1:1`, `3:4`, `4:3`, `9:16`, `16:9` |
| `resolution` | No | `1k` \| `2k` | xAI resolution tier |
| `n` | No | number | Image count (xAI 1–10, Google 1–4) |
| `purpose` | No | string | Storage path segment, e.g. `og`, `news-featured` |
| `refCode` | No | string | Optional tracking id |
| `seed` | No | number | Reproducibility hint (provider-dependent) |

**OG preset:** `aspectRatio: "2:1"` on xAI (~1200×630). For Google Imagen use `16:9` as nearest OG ratio.

Ask your MCP-connected agent in natural language:

```
Generate a professional Ring Platform banner with vibrant gradient,
aspect ratio 2:1, purpose og
```

Or invoke the tool explicitly:

```
ring-image-create prompt "community meetup photo, warm lighting" aspectRatio 16:9 purpose news-featured
```

**Enable the MCP gateway** on the Ring clone — set `RING_MCP_ACCESS_KEY` in `.env.local` and restart `npm run dev`.

**Configure image generation** — `XAI_API_KEY` (or `GOOGLE_GENAI_API_KEY`), plus ring-filebase (`FILE_BACKEND=ringbase`, `RINGBASE_API_URL`, `RINGBASE_API_TOKEN`).

**Register `ring-mcp`** in Cursor with matching `RING_MCP_ACCESS_KEY` and `RING_API_BASE_URL` (e.g. `http://localhost:3000` for ring-platform.org).

**Verify** — run `ring-health`, then `ring-image-create` with a short test prompt. Expect a `url` in the response.

{`curl -s -X POST http://localhost:3000/api/mcp/v1/images/generate \\
  -H "Authorization: Bearer YOUR_RING_MCP_ACCESS_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "prompt": "professional tech referral banner, vibrant gradient",
    "provider": "xai",
    "aspectRatio": "2:1",
    "purpose": "og"
  }'`}

{`// POST /api/images/generate — requires Auth.js admin/superadmin session
// app/api/images/generate/route.ts`}

{`import { ImageConductor } from '@/lib/images/conductor/image-conductor'

const result = await ImageConductor.generate({
  prompt: 'Ring Platform community meetup photo',
  purpose: 'news-featured',
  aspectRatio: '16:9',
  actorId: userId,
})

if (result.success && result.images?.[0]?.url) {
  const featuredImage = result.images[0].url
}`}

## Response shape

MCP gateway wraps the conductor result in `{ success, data }`:

{`{
  "success": true,
  "data": {
    "success": true,
    "provider": "xai",
    "model": "grok-imagine-image-quality",
    "prompt": "professional tech banner",
    "images": [
      {
        "url": "https://cdn.example/.../generated/og/....png",
        "fileId": "...",
        "size": 245760,
        "contentType": "image/png",
        "recordId": "uuid"
      }
    ]
  }
}`}

## Environment

{`# MCP gateway
RING_MCP_ACCESS_KEY=your-long-random-token

# ImageConductor
IMAGE_GEN_PROVIDER=xai
IMAGE_GEN_STORAGE_PREFIX=generated
IMAGE_GEN_POLL_TIMEOUT_MS=120000

XAI_API_KEY=your_key
XAI_API_BASE_URL=https://api.x.ai/v1
XAI_IMAGE_MODEL=grok-imagine-image-quality
XAI_IMAGE_RESOLUTION=2k
XAI_IMAGE_ASPECT_RATIO=1:1

# Optional Google Imagen
GOOGLE_GENAI_API_KEY=
GOOGLE_IMAGE_MODEL=imagen-4.0-generate-001

# Storage (ring-filebase)
FILE_BACKEND=ringbase
RINGBASE_API_URL=
RINGBASE_API_TOKEN=`}

## Database

Migration `data/migrations/006_generated_images_schema.sql` adds the `generated_images` audit table (mirrored in `data/schema.sql`).

## Troubleshooting

| Symptom | Check |
|---------|--------|
| `Invalid service token` / 401 | `RING_MCP_ACCESS_KEY` in MCP client matches `RING_MCP_ACCESS_KEY` on clone |
| `prompt is required` | Pass non-empty `prompt` |
| `XAI_API_KEY is not configured` | Key in `.env.local`, restart dev server |
| Upload failed | `RINGBASE_API_TOKEN`, `FILE_BACKEND=ringbase` |
| Timeout | Raise `IMAGE_GEN_POLL_TIMEOUT_MS` (default 120000) |
| Empty / policy rejection | Provider quota, prompt policy, or model name drift |

The MCP service token grants **SUPERADMIN**-equivalent access on the clone — including image generation billed to your provider keys. Rotate tokens per environment; never commit secrets.

## Related

  
- **[ring-news-generate](/docs/development/generative-newsroom.md)** — Autonomous newsroom — uses ImageConductor for featured images.

  
- **[News feature](/docs/features/news.md)** — Member blog UI with `GenerateImageDialog`.