# Artillect CLI

Artillect CLI — генерация картинок, видео, аудио и 3D из терминала. Тот же аккаунт и баланс, что в студии.

Это инструкция для работы командами в терминале. Если вы хотите пользоваться генераторами в браузере, начните со [справки Studio](/docs/knowledge/start/first-result.md). Другие способы подключения собраны в [технической документации](/docs/).

Интерактивная страница: [/docs/cli](/docs/cli).

## Содержание

- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [Примеры](#примеры)
- [Элементы и storage](#элементы-и-storage)
- [Задачи](#задачи)
- [Команды](#команды)
- [Флаги](#флаги)
- [Результат](#результат)
- [Обновление](#обновление)
- [Если не работает](#если-не-работает)

## Установка

```bash
npm install -g @artillect/cli
```

Нужен Node.js 20+. Без глобальной установки: `npx @artillect/cli@latest --help`.

## Быстрый старт

```bash
artillect auth login
artillect generate image --prompt "кот в космосе" --wait --open
```

Ключ также можно задать через `ARTILLECT_API_KEY`.

## Примеры

### Картинка

```bash
artillect generate image \
  --model seedream-5-pro \
  --prompt "современная архитектура, золотой час" \
  --wait --open
```

### Видео — Grok

```bash
artillect generate video grok-imagine-video \
  --prompt "кот идёт по комнате, простой план" \
  --wait --open
```

### Видео — Kling 3 со стартовым кадром

```bash
artillect generate video kling-3 \
  --prompt "медленный проезд камеры через лес на рассвете" \
  --start-image ./first.png \
  --wait
```

### Видео — Seedance 2.5 с референсом

```bash
artillect generate video seedance-2.5 \
  -p "герой идёт по улице, спокойный план" \
  --duration 10 \
  --resolution 1080p \
  --output-format mov \
  --ref-image ./sheet.png \
  --project 12 \
  --wait
```

### Проверить цену перед запуском

```bash
artillect estimate image -m seedream-5-pro -p "кот в космосе"
artillect estimate video -m grok-imagine-video -p "кот идёт"
artillect estimate audio -m suno-v6 -p "ambient synthwave"
artillect estimate mesh -m meshy-v7-t2m -p "low-poly robot"
```

### Аудио и SwitchX

```bash
artillect generate audio -p "ambient synthwave for a night drive" --style synthwave --wait
artillect generate switchx --source ./clip.mp4 --reference-image https://example.com/subject.png --wait
```

### Каталог

```bash
artillect models list
artillect models list -k video
artillect models get grok-imagine-video --json
```

`models list` и `models get` показывают лимиты из Public API. Для генераторов это
`prompt ≤ N симв.`; для chat-моделей — контекст модели, максимум вывода провайдера,
а также практические потолки Artillect. Например, `seedance-2.5` принимает prompt до
примерно **40 000 символов** (лимит провайдера — 10 000 токенов, оценка 4 символа/токен).

```bash
artillect models get seedance-2.5
artillect models list -k chat
```

У chat-моделей `context_length_tokens` — окно модели, а
`provider_max_output_tokens` — максимум выбранного провайдера. Public API дополнительно
использует токеновый контекст и максимум вывода выбранной chat-модели без общего символьного cap; HTTP JSON ограничен 8 MiB. [Изменения для интеграторов](/docs/api-updates/2026-10-16.md).

## Элементы и storage

Файл в storage — стабильный `ast_…`. Список страницами: если в конце есть `дальше --cursor …`, повторите команду с этим флагом.

В хранилище можно хранить инструкции агентов `AGENTS.md`, определения skills `SKILL.md` и сопроводительные Markdown/TXT-документы (UTF-8, до 10 МиБ). Клиент сам загружает скачанные инструкции; сохранение файла не запускает агента.

```bash
artillect upload ./SKILL.md --json
artillect assets list --kind file --query SKILL --json
artillect assets get ast_… --json
artillect assets download ast_… --out ./skills/example/SKILL.md --json
artillect assets copy ast_… --project 12 --json
artillect assets delete ast_… --json
```

После `upload` используйте возвращённый `asset_id` вместо `ast_…`. `--out` — путь к файлу; существующий файл не перезаписывается. Загрузка без `--project` сохраняет файл в личное хранилище. Многофайловый skill сохраняется по документам; восстановите их относительные пути в своём клиенте. [Тот же цикл через API и MCP](/docs/knowledge/guides/storage-and-privacy.md).

Элемент — запись в библиотеке проекта: в промпте `@Hero`. Хранится в Kling-shape. Как уходит в модель, решает сервер:

- `kling-3` / `kling-o3` — нативные элементы провайдера (не turbo)
- остальные модели — `@Hero` парсится, frontal подставляется как референс

Нужен `--project`.

```bash
artillect projects list
artillect upload ./hero.png --project 12
artillect assets list --project 12
artillect assets list --project 12 --cursor ast_01ARZ3NDEKTSV4RRFFQ69G5FAV
```

```bash
artillect elements create --project 12 --name Hero --file ./hero.png
artillect generate video kling-3 \
  --project 12 \
  --prompt "@Hero идёт по улице" \
  --start-image ast_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --wait
```

```bash
artillect generate video seedance-2 \
  --project 12 \
  --prompt "@Hero идёт по улице" \
  --wait
```

`--input` / `--start-image` / `--end-image` принимают локальный файл, HTTPS или `ast_…`.
Изображения HEIC/HEIF, AVIF, WebP, TIFF, GIF и SVG принимаются и нормализуются сервером перед передачей провайдеру. Для видео нужен обычный upload/URL: direct presign для видео не поддерживается.

## Задачи

Без `--wait` команда сразу печатает `task_id`. Дальше можно смотреть статус или ждать файл.

```bash
artillect generate image --prompt "кот"
artillect generate get <task_id>
artillect generate wait <task_id> --open
```

## Команды

| Команда                | Зачем                                                                         |
| ---------------------- | ----------------------------------------------------------------------------- |
| `artillect auth`       | login / logout / status                                                       |
| `artillect balance`    | баланс токенов                                                                |
| `artillect health`     | проверка доступности Public API                                               |
| `artillect feedback`   | отправить JSON feedback                                                       |
| `artillect models`     | list / get — каталог и схема параметров с сервера                             |
| `artillect generate`   | image / video / audio / switchx / mesh / upscale / get / wait / cancel / list |
| `artillect estimate`   | цена до генерации, без списания                                               |
| `artillect upload`     | загрузить файл, получить ast_…                                                |
| `artillect assets`     | list / get / copy — storage ast_…                                             |
| `artillect projects`   | CRUD / roles / members / invite / generations / analytics / billing           |
| `artillect elements`   | list / get / create — @Name в проекте                                         |
| `artillect element`    | update / delete / reorder                                                     |
| `artillect generation` | tags / like / copy / move / delete                                            |
| `artillect tags`       | list / create / delete тегов проекта                                          |
| `artillect favorites`  | список избранных генераций проекта                                            |
| `artillect chat`       | completion / server-side threads                                              |
| `artillect webhook`    | get / upsert / delete / rotate / deliveries                                   |
| `artillect media`      | edit / get / cancel (WIP; в production feature flag выключен)                 |

Подсказки по флагам: `artillect --help`, `artillect generate image --help`.

`artillect generate cancel <task_id>` возвращает токены только в первые 4 секунды,
до отправки задачи провайдеру. После этого сервер отвечает `409 GENERATION_NOT_CANCELLABLE`.

## Флаги

| Флаг                | Зачем                                                            |
| ------------------- | ---------------------------------------------------------------- |
| `--wait`            | ждать готовности и скачать файл                                  |
| `--wait-timeout`    | лимит ожидания, по умолчанию `20m` (ещё `90s`, `10m`)            |
| `--out`             | папка для файлов, по умолчанию текущая                           |
| `--open`            | открыть скачанный файл                                           |
| `--json`            | сырой JSON для скриптов                                          |
| `--project`         | id проекта: лента, storage, @элементы                            |
| `--cursor`          | следующая страница list                                          |
| `--duration`        | длительность видео, секунды                                      |
| `--resolution`      | `720p` / `1080p` / `4k` / размер картинки                        |
| `--aspect-ratio`    | например `16:9`, `1:1`                                           |
| `--quality`         | качество картинки, если модель его принимает                     |
| `--size`            | размер image-слоя: `auto`, `1K`, `1.5K`, `2K`                    |
| `--num-images`      | количество изображений, если модель поддерживает                 |
| `--output-format`   | `jpeg` / `png` / `webp`; для Seedance 2.5 также `mp4` / `mov`    |
| `--sync-mode`       | вернуть data URI/base64 вместо persisted URL, где поддерживается |
| `--seed`            | seed для воспроизводимой генерации, где поддерживается           |
| `--task`            | видео-задача: `t2v`, `i2v`, …                                    |
| `--seedance-mode`   | `quality` или `fast`                                             |
| `--start-image`     | стартовый кадр видео                                             |
| `--end-image`       | финальный кадр видео                                             |
| `--source-video`    | исходное видео для edit/v2v/motion                               |
| `--audio-url`       | аудио для avatar/lipsync                                         |
| `--motion-video`    | motion reference video                                           |
| `--ref-image`       | референс-картинки (повторяемый)                                  |
| `--ref-video`       | референс-видео                                                   |
| `--ref-audio`       | референс-аудио                                                   |
| `--ref-file`        | один публичный URL документа для Wan 3/Prime                     |
| `--ref-link`        | один публичный URL веб-страницы для Wan 3/Prime                  |
| `--audio`           | аудиодорожка Wan 3/Prime: `true` / `false`                       |
| `--generate-audio`  | генерировать аудио у поддерживаемых video-моделей                |
| `--element-name`    | имена Elements проекта, повторяемый аргумент                     |
| `--multi-prompt`    | JSON-массив prompt для multi-shot                                |
| `--multi-shots`     | количество shots                                                 |
| `--keep-audio`      | сохранить аудио исходного видео                                  |
| `--cfg-scale`       | CFG scale у поддерживаемых Kling-задач                           |
| `--nsfw-checker`    | включить/выключить checker у поддерживаемых Wan-задач            |
| `--extra`           | JSON-объект, дополнительные поля тела API                        |
| `--billing-source`  | источник списания: `owner` или `self`                            |
| `--tag-id`          | project tag ids через запятую                                    |
| `--idempotency-key` | безопасный retry платного submit                                 |

`--extra` принимает JSON-объект дополнительных полей тела API. Названия, типы и допустимые значения сверяйте с `parameters` текущей карточки модели в `GET /api/v1/models/`; наличие поля в `--extra` не отменяет серверную проверку.

## Результат

С `--wait` CLI печатает путь к файлу в текущей папке. С `--open` сразу открывает его. Без флага — `open ./artillect-….png` на macOS или клик по пути в Terminal.

Media operations (`artillect media`) пока являются WIP: в production они возвращают `503 MEDIA_OPERATIONS_WIP`, пока не включён `MEDIA_OPERATIONS_PUBLIC_ENABLED`.

## Обновление

```bash
npm i -g @artillect/cli@latest
```

npm сам пакет на компьютере не обновляет. Когда выйдет версия, CLI подскажет в терминале.

## Если не работает

- `Нет входа` — `artillect auth login` или `ARTILLECT_API_KEY`.
- Каталог всегда с сервера: `artillect models list`. Используйте slug из текущего каталога.
- Для скриптов: `--json`. Прогресс идёт в stderr, результат — в stdout.

## Midjourney 8 и Mureka V9

`midjourney-8` создаёт четыре изображения за запрос, принимает до четырёх `input_urls`. Версии `8.2` (по умолчанию) и `8.1`; `speed=relax|fast|turbo` — 6/7/12 токенов за запрос. Доступны `quality`, `style`, `seed`, `negative_prompt`, `stylize`, `chaos`, `weird`, `tile`, `raw`, `draft`, `hd`, `iw`, `cw`, `sw`, `cref`, `sref`, `dref`, `dw`. Список значений и лимитов — в `/api/v1/models/`. Модель поддерживает новую генерацию; действия над ранее созданными задачами не входят в этот endpoint.

`mureka-v9` требует `lyrics` (1–3000 символов), принимает описание стиля `prompt` (до 1024 символов), `number_of_songs=1|2|3` (6/10/15 токенов), `output_format=mp3|wav|flac`. `reference_id`, `vocal_id`, `melody_id` — ID из системы загрузки Mureka, не URL файлов. Обе модели доступны в Studio, REST, MCP и CLI; стоимость учитывает выбранные параметры.

CLI: `artillect generate image --model midjourney-8 --prompt "A quiet garden" --version 8.2 --speed relax --extra '{"stylize":200}'`; `artillect generate audio --model mureka-v9 --lyrics "Morning light, a new beginning" --prompt "Warm acoustic pop" --number-of-songs 1 --output-format mp3`. MCP `generate_image` / `generate_audio` принимают соответствующие поля напрямую.

Seedance: `bitrate_mode=default|standard|high`, `watermark`, `return_last_frame` (кроме Mini); 2.5 и 2.5 Eco также `seed`, `web_search`, `output_format=mp4|mov`. CLI предоставляет `--bitrate-mode`, `--watermark`, `--return-last-frame`.

## Сайт с медиа Artillect и продолжение задачи

В Hermes/OpenCode подключите одновременно Provider и MCP:
[OpenCode](/provider/opencode/) · [Hermes](/provider/hermes/).
MCP prompt `website_media` описывает сценарий: выбранный проект → оценки цены →
генерация → `get_task` → локальные файлы сайта. Агенту нужны терминал и рабочая папка.
Сохраняйте `project_id` и `task_id` каждого ассета в локальный
`artillect-assets.json`, передавайте проект при генерации.

Для скачивания **уже созданной** задачи используйте:

```bash
artillect generate wait TASK_ID --out public/assets --json
```

Команда опрашивает существующую задачу и возвращает `saved[]` с путями файлов;
новую генерацию не отправляет. Работает для изображений, видео, аудио и 3D.
Проверьте файлы, переименуйте с сохранением фактического формата и сохраните пути
в manifest. В код сайта вставляйте локальные пути; capability URL из результата
не сохраняйте в репозитории. Если скачивание оборвалось, повторите `wait` с тем же
ID, а не `generate image/video/audio/mesh`. Если файл уже корректен, используйте его.
При неопределённом submit повторяйте тот же payload с прежним
`--idempotency-key` только в пределах 24-часового окна; после истечения окна сначала
сверьте историю проекта. Новый submit может потребовать нового списания.

Бесплатная проверка ключа — прямые GET `/api/v1/provider/models/` и `/api/v1/me/`;
MCP `get_started` / `get_balance` также бесплатны при прямом вызове инструмента.
Сообщение агенту использует платную LLM, даже когда он вызывает бесплатный инструмент.
Бюджеты Provider и генерации медиа не образуют общий автоматический лимит задачи.

## Дополнительные общие примеры

### Видео — Wan 3 Prime

```bash
artillect generate video wan-30-prime \
  --prompt "сделай ролик по материалам продукта" \
  --ref-file https://example.com/product.pdf \
  --resolution 720P \
  --duration 8 \
  --audio true \
  --seed 12345 \
  --wait
```

### Видео — MiniMax H3 Max

```bash
artillect generate video minimax-h3-max \
  --prompt "камера плавно облетает стеклянный павильон" \
  --ref-image ./subject.png \
  --ref-video ./motion.mp4 \
  --ref-audio ./voice.mp3 \
  --resolution 480P \
  --duration 8 \
  --aspect-ratio 16:9 \
  --prompt-expansion-mode quality \
  --enable-safety-checker true \
  --wait
```

### Картинка — Meta Muse Image

```bash
artillect generate image \
  --model muse-image \
  --prompt "poster for a futuristic concert" \
  --aspect-ratio 16:9 \
  --num-images 3 \
  --output-format webp \
  --wait --open
```

### Картинка — примерка одежды

```bash
artillect generate image \
  --model google-virtual-try-on \
  --input ./person.jpg \
  --input ./jacket.jpg \
  --num-images 2 \
  --wait --open
```

### 3D — Meshy multi-view

```bash
artillect generate mesh \
  --model meshy-v7-multi-i2m \
  --image ./front.png \
  --image ./side.png \
  --target-polycount 30000 \
  --should-texture true \
  --enable-pbr true \
  --wait --open
```

### Видео — FLUX Video Upscale

```bash
artillect generate upscale \
  --model flux-video-upscale \
  --video ./clip.mp4 \
  --upscale-factor 2 \
  --creativity 0 \
  --wait --open
```