---
title: "ring-image-create"
description: "Довідник інструмента MCP — генерація зображень через ImageConductor (xAI Grok Imagine або Google Imagen) зі збереженням у ring-filebase"
locale: "uk"
---
# `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 проти 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` |
| **Потрібне підтвердження** | Ні (генерація та зберігання без змін) |

## Параметри

| Параметр | Обов’язковий | Тип | Примітки |
|-----------|----------|------|-------|
| `prompt` | **Так** | string | Природномовний опис зображення |
| `provider` | Ні | `xai` \\| `google` | Типовий з `IMAGE_GEN_PROVIDER` |
| `model` | Ні | string | Перевизначення моделі провайдера |
| `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` |
| `refCode` | Ні | string | Необов’язковий ID відстеження |
| `seed` | Ні | number | Підказка відтворюваності |

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

Попросіть підключеного до MCP агента природною мовою:

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

Увімкніть MCP-шлюз у клоні Ring і налаштуйте генерацію зображень.

Зареєструйте `ring-mcp` у Cursor і перевірте `ring-health`.

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

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

## Форма відповіді

Шлюз MCP обгортає результат conductor у `{ success, data }`.

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

## Середовище

{`RING_MCP_ACCESS_KEY=your-long-random-token
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
GOOGLE_GENAI_API_KEY=
GOOGLE_IMAGE_MODEL=imagen-4.0-generate-001
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 | Токени MCP-клієнта і клону збігаються |
| `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` |

Сервісний токен MCP надає доступ, еквівалентний **SUPERADMIN**, зокрема до генерації зображень за рахунок ключів провайдера. Ротуйте токени для кожного середовища й ніколи не комітьте секрети.

## Пов’язані матеріали

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

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