---
title: "ring-image-create"
description: "Справочник инструмента MCP — генерация изображений через ImageConductor (xAI Grok Imagine или Google Imagen) и сохранение в ring-filebase"
locale: "ru"
---
# `ring-image-create`

Генерирует изображение из естественно-языкового prompt, загружает его в **ring-filebase**, сохраняет строку аудита в `generated_images` и возвращает постоянный CDN URL.

Операторы и агенты вызывают **`ring-image-create`** через `ring-mcp`. Шлюз бьёт в `POST /api/mcp/v1/images/generate`, который запускает **`ImageConductor`** (`lib/images/conductor/image-conductor.ts`) с сервисным актором MCP как `actorId`. Провайдер по умолчанию — **xAI** (`IMAGE_GEN_PROVIDER=xai`).

  
- **[Центр MCP-инструментов](/docs/mcp.md)** — Обзор Ring MCP, область kingdom vs clone, предпосылки.

  
- **[Генеративные изображения (ImageConductor)](/docs/development/generative-images.md)** — Архитектура, админ UI, программный API, устранение неисправностей.

  
- **[Ring MCP Server](/docs/development/ring-mcp.md)** — Настройка токенов, `ring-health`, полный каталог инструментов.

  
- **[Окружение](/docs/deployment/environment.md)** — Переменные окружения изображений и хранилища на клоне.

```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
```

## Идентичность инструмента

| Поле | Значение |
|-------|--------|
| **Имя MCP-инструмента** | `ring-image-create` |
| **HTTP-маршрут** | `POST /api/mcp/v1/images/generate` |
| **MCP-сервер** | `AI-RING/ring-mcp/lib/tools.js` |
| **Обработчик шлюза** | `app/api/mcp/v1/images/generate/route.ts` |
| **Conductor** | `lib/images/conductor/image-conductor.ts` |
| **Требуется confirm** | Нет (генерация + хранение без деструктивных мутаций) |

## Параметры

| Параметр | Обязательный | Тип | Примечания |
|-----------|----------|------|-------|
| `prompt` | **Да** | string | Естественно-языковое описание изображения |
| `provider` | Нет | `xai` \| `google` | По умолчанию из `IMAGE_GEN_PROVIDER` (обычно `xai`) |
| `model` | Нет | string | Переопределение модели провайдера (см. env defaults ниже) |
| `aspectRatio` | Нет | string | xAI: гибкий; Google: `1:1`, `3:4`, `4:3`, `9:16`, `16:9` |
| `resolution` | Нет | `1k` \| `2k` | Уровень разрешения xAI |
| `n` | Нет | number | Число изображений (xAI 1–10, Google 1–4) |
| `purpose` | Нет | string | Сегмент пути хранилища, напр. `og`, `news-featured` |
| `refCode` | Нет | string | Опциональный tracking id |
| `seed` | Нет | number | Подсказка воспроизводимости (зависит от провайдера) |

**OG preset:** `aspectRatio: "2:1"` на xAI (~1200×630). Для Google Imagen используйте `16:9` как ближайшее OG-соотношение.

Попросите подключённого к MCP агента на естественном языке:

```
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
```

**Включите MCP-шлюз** на клоне Ring — задайте `RING_MCP_ACCESS_KEY` в `.env.local` и перезапустите `npm run dev`.

**Настройте генерацию изображений** — `XAI_API_KEY` (или `GOOGLE_GENAI_API_KEY`), плюс ring-filebase (`FILE_BACKEND=ringbase`, `RINGBASE_API_URL`, `RINGBASE_API_TOKEN`).

**Зарегистрируйте `ring-mcp`** в Cursor с совпадающими `RING_MCP_ACCESS_KEY` и `RING_API_BASE_URL` (напр. `http://localhost:3000` для ring-platform.org).

**Проверьте** — запустите `ring-health`, затем `ring-image-create` с коротким тестовым prompt. Ожидайте `url` в ответе.

{`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
}`}

## Форма ответа

Шлюз MCP оборачивает результат conductor в `{ 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"
      }
    ]
  }
}`}

## Окружение

{`# 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=`}

## База данных

Миграция `data/migrations/006_generated_images_schema.sql` добавляет таблицу аудита `generated_images` (также отражена в `data/schema.sql`).

## Устранение неисправностей

| Симптом | Проверка |
|---------|--------|
| `Invalid service token` / 401 | `RING_MCP_ACCESS_KEY` в MCP-клиенте совпадает с `RING_MCP_ACCESS_KEY` на клоне |
| `prompt is required` | Передайте непустой `prompt` |
| `XAI_API_KEY is not configured` | Ключ в `.env.local`, перезапустите dev-сервер |
| Upload failed | `RINGBASE_API_TOKEN`, `FILE_BACKEND=ringbase` |
| Timeout | Поднимите `IMAGE_GEN_POLL_TIMEOUT_MS` (по умолчанию 120000) |
| Пустой ответ / policy rejection | Квота провайдера, политика prompt или дрейф имени модели |

Сервисный токен MCP даёт доступ, эквивалентный **SUPERADMIN**, на клоне — включая генерацию изображений за счёт ключей провайдера. Ротируйте токены по средам; никогда не коммитьте секреты.

## Связанное

  
- **[ring-news-generate](/docs/development/generative-newsroom.md)** — Автономная редакция — использует ImageConductor для featured images.

  
- **[Функция News](/docs/features/news.md)** — UI блога участника с `GenerateImageDialog`.