Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
ring-image-createGenerate 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).
Ring MCP overview, kingdom vs clone scope, prerequisites.
Architecture, admin UI, programmatic API, troubleshooting.
Token setup, ring-health, full tool catalog.
Image and storage env vars on the clone.
| 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) |
| 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 |
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:
Or invoke the tool explicitly:
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.
MCP gateway wraps the conductor result in { success, data }:
Migration data/migrations/006_generated_images_schema.sql adds the generated_images audit table (mirrored in data/schema.sql).
| 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.
ring-image-createGenerate 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).
Ring MCP overview, kingdom vs clone scope, prerequisites.
Architecture, admin UI, programmatic API, troubleshooting.
Token setup, ring-health, full tool catalog.
Image and storage env vars on the clone.
| 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) |
| 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 |
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:
Or invoke the tool explicitly:
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.
MCP gateway wraps the conductor result in { success, data }:
Migration data/migrations/006_generated_images_schema.sql adds the generated_images audit table (mirrored in data/schema.sql).
| 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.
ring-image-createGenerate 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).
Ring MCP overview, kingdom vs clone scope, prerequisites.
Architecture, admin UI, programmatic API, troubleshooting.
Token setup, ring-health, full tool catalog.
Image and storage env vars on the clone.
| 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) |
| 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 |
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:
Or invoke the tool explicitly:
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.
MCP gateway wraps the conductor result in { success, data }:
Migration data/migrations/006_generated_images_schema.sql adds the generated_images audit table (mirrored in data/schema.sql).
| 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.
| 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) |
Generate a professional Ring Platform banner with vibrant gradient,
aspect ratio 2:1, purpose og
ring-image-create prompt "community meetup photo, warm lighting" aspectRatio 16:9 purpose news-featured| 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) |
Generate a professional Ring Platform banner with vibrant gradient,
aspect ratio 2:1, purpose og
ring-image-create prompt "community meetup photo, warm lighting" aspectRatio 16:9 purpose news-featured| 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) |
Generate a professional Ring Platform banner with vibrant gradient,
aspect ratio 2:1, purpose og
ring-image-create prompt "community meetup photo, warm lighting" aspectRatio 16:9 purpose news-featured