---
id: collections-regenerate
title: "POST /api/collections/:id/regenerate — (Пере)генерация коллекции"
domain: collections
kind: api-method
http: "POST /api/collections/:id/regenerate"
---

# POST /api/collections/:id/regenerate — (Пере)генерация коллекции {#collections-regenerate}

## Сводка

| Поле | Значение |
|---|---|
| **HTTP** | `POST /api/collections/:id/regenerate` |
| **Auth** | `—` |
| **Scope токена** | `read_write` |
| **PG-функции** | `api.create_collection_generation_attempt`, `api.finalize_collection_generation_attempt` |
| **Таблицы** | `collection_generation_attempt`, `collection`, `collection_block`, `collection_layer`, `collection_specialty`, `collection_edge` |
| **SRM** | SRM-328 |
| **RP (права)** | — |
| **Файл роута** | `server/routes/collections.js` |
| **Статус** | done |

**Аргументы запроса** (best-effort из хендлера; путь-параметры опущены):

| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
| `keep_block_ids` | body | | _подтвердить_ |
| `messages` | body | | _подтвердить_ |
| `mode` | body | | _подтвердить_ |
| `params` | body | | _подтвердить_ |
| `quality` | body | | _подтвердить_ |
| `mode` | query | | _подтвердить_ |

**Коды ответов/ошибок** (из хендлера): `202`, `400`, `409`, `429`, `500` (+ `200`) — _уточнить причины вручную_

Запись — нужен токен со scope `read_write` (см. [Конвенции](../../../shared/conventions.md#conventions)). Управление коллекцией — операция администратора-владельца: вызов разрешён только site-admin'у или org-admin'у организации-владельца коллекции (`owner_org_id`); глобальные коллекции (`owner_org_id IS NULL`) — только site-admin. Иначе — `403`.

Метод унифицированный: один эндпоинт и для первичной генерации, и для всех видов перегенерации. Поведение и формат ответа зависят от `mode`.

**Тело запроса (JSON):**

| Поле | Тип | Обяз. | Назначение |
|---|---|---|---|
| `mode` | string | да | `initial` \| `blocks-only` \| `with-keep` \| `propose` (см. ниже) |
| `params` | object | да | Рамки по осям: `layers`, `blocks`, `specialties` — каждая `{ "min": int\|null, "max": int\|null }` (1–100). Любую границу можно оставить `null`. `min > max` → `400` |
| `messages` | array | да | История запроса к LLM: 1–10 элементов `{ "role": "user"\|"assistant", "content": string }` (`content` 1–50000 символов) |
| `quality` | string | нет | `pro` (по умолчанию для коллекций) или `fast` — [Pro-режим](../../../shared/glossary.md#term-pro-mode) |
| `keep_block_ids` | array | нет¹ | id блоков, которые сохранить. Обязателен и непуст для `mode: with-keep` |

¹ Только для `with-keep`. Лишние поля запрещены (схема строгая, `additionalProperties: false`).

**Режимы и формат ответа.** Это ключевое различие метода:

- `propose` — **предпросмотр без записи**. Генерация прогоняется, в коллекцию ничего не пишется, ответ — обычный JSON (не поток). Используйте, чтобы «примерить» параметры.
- `initial`, `blocks-only`, `with-keep` — **applied-режимы**: результат записывается в коллекцию, а ответ отдаётся как поток [Server-Sent Events](../../../shared/glossary.md#term-sse-generation) (`Content-Type: text/event-stream`). Соединение держится открытым до конца генерации. Контент-негоциация (`Accept: text/markdown`, `ETag`/`304`) к applied-режимам не применяется.

**Пример запроса (applied, SSE):**

```bash
curl -N -X POST https://specbuilder.vnimanie.ai/api/collections/a1b2c3d4-.../regenerate \
  -H "Authorization: Bearer tak_..." \
  -H "Content-Type: application/json" \
  -d '{"mode":"initial","quality":"pro","params":{"layers":{"min":3,"max":5},"blocks":{"min":null,"max":20},"specialties":{"min":null,"max":null}},"messages":[{"role":"user","content":"Коллекция для precision agriculture"}]}'
```

`-N` (`--no-buffer`) обязателен для applied-режимов — иначе curl придержит поток и события не будут видны в реальном времени.

**Ответ `200` для `propose`** (JSON, ничего не записано):

```json
{
  "attempt_id": "f9e8d7c6-...",
  "result_summary": { "layers_count": 4, "blocks_count": 18, "specialties_count": 9 },
  "duration_ms": 14230
}
```

**Поток событий (applied):** каждое событие — строки `event: <тип>` и `data: <json>`, разделённые пустой строкой. По ходу приходят `stage` (смена этапа), granular-события `layer` / `specialty` / `block` / `edge`, а в `pro` — ещё `quality_phase`. В конце — `done` с `attempt_id`, `result_summary`, `duration_ms`; при сбое — `error`.

```
event: stage
data: {"stage":"decomposition","status":"started"}

event: block
data: {"id":"data-collection","name":"Сбор данных","layer_id":"FOUNDATION","default_specialties":["ml-engineer"]}

event: edge
data: {"source_id":"data-collection","target_id":"model-training"}

event: done
data: {"attempt_id":"f9e8d7c6-...","result_summary":{"layers_count":4,"blocks_count":18,"specialties_count":9},"duration_ms":51200}
```

**Конкурентность.** На одну коллекцию допускается одна applied-генерация одновременно. Если в окне 10 минут уже идёт другая попытка, applied-вызов завершится `409` **до** открытия потока (обычный JSON-ответ с ошибкой), а не повисшим SSE. `propose` под это окно не попадает. Прочие ошибки генерации отдаются как `500` (в applied-режиме — событием `error` в уже открытом потоке).

Параметры успешно применённого прогона можно прочитать позже через [последнюю применённую генерацию](last-applied-attempt.md#collections-last-applied-attempt) — обычно для предзаполнения формы.

**Риск и подтверждение.** Метод помечен `COSTLY_LLM` (платная генерация). Токену сервер требует `{"confirm": true}` в теле — без него `409` (см. [Агентные конвенции записи](../../../shared/conventions.md#agent-write-conventions)); это касается всех режимов, включая `propose`.

**Фоновый режим (`?mode=async`).** Для applied-режимов токен может добавить `?mode=async` — вместо SSE придёт `202 {job_id, poll}`. Опрашивайте [статус задачи](get-job.md#collections-get-job) по `poll`-URL и при необходимости [отменяйте](cancel-job.md#collections-cancel-job). При переполнении очереди — `429`. Async доступен только токену; cookie-клиент всегда получает SSE. Предварительно прикинуть размеры без запуска LLM можно через [оценку размеров](estimate.md#collections-estimate).

<!-- gen:start:related -->
## Связанные
- Экраны: [Редактор коллекции](../screens/collection-editor.md#collections-screen-collection-editor)
- [Конвенции](../../../shared/conventions.md#conventions) · [Роли](../../../shared/roles.md#roles) · [Ошибки](../../../shared/errors.md#errors) · [Глоссарий](../../../shared/glossary.md#glossary)
<!-- gen:end:related -->

---

Human view: https://docs.vnimanie.ai/specbuilder/v1/domains/collections/api/regenerate/