# Generate

Commands that make pictures, video takes, voice lines and words, list models, save finished jobs, and run canvas boards.

Every command on this page needs a signed-in computer. Signed out, each one prints `You are not signed in. Ask your agent to run minicut login.` and exits with code 10. Flags every command takes, and every exit code, are on [Global options](/docs/cli/global-options).

## minicut gen image

Makes one picture for a character, location, prop or style in your library.

### Usage

```text Usage
minicut gen image OUT_FILE --prompt-file PROMPT_FILE --model MODEL --target KIND:ID [--project PROJECT] [--episode EPISODE] [--size W*H | --res RESOLUTION --aspect RATIO | --quality QUALITY] [--on {blank|PICTURE}] [--ref PICTURE ...] [--name NAME] [--json]
```

Replace the following:

- `OUT_FILE`: the picture file to make, such as `lin-xia.png`.
- `PROMPT_FILE`: a text file with the words that describe the picture.
- `MODEL`: an image model name from [minicut models](#minicut-models).
- `KIND:ID`: what the picture is for. `KIND` is `character`, `location`, `prop` or `style`, and `ID` is the item's id.
- `PROJECT`: a project id or the path to a project folder.
- `EPISODE`: an episode id such as `ep01`.
- `W*H`: the size in pixels, such as `1024*1536`.
- `RESOLUTION`, `RATIO`, `QUALITY`: values the model lists in its settings.
- `PICTURE`: a picture file on your computer.
- `NAME`: the short name people read on the asset card.

### Details

This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. It does not wait for the picture. It sends the job and returns, and [minicut jobs](#minicut-jobs) saves the picture into your library when it is done.

With no size flag, the picture is asked at the project's screen shape when the model lists it. When it does not, the command says so and asks you to add `--aspect`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--prompt-file` | file | none | The words that describe the picture. Needed |
| `--model` | name | none | The image model. Needed. There is no default model |
| `--target` | `KIND:ID` | none | The library item the picture is for. Needed |
| `--project` | id or folder | none | The project the item belongs to |
| `--episode` | episode id | none | The episode the picture is for |
| `--size` | `W*H` | the project's shape | The size in pixels |
| `--res` | value | none | The resolution, used with `--aspect` |
| `--aspect` | ratio | the project's shape | The screen shape, such as `9:16` |
| `--quality` | value | none | The quality setting the model offers |
| `--on` | `blank` or picture | none | A picture to edit. `blank` starts from a white picture, and needs `--size` |
| `--ref` | picture | none | A reference picture. Repeat it for more than one |
| `--name` | text | none | The name people read on the asset card |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Find an image model

```bash Terminal
minicut models --kind image
```

#### Make a character picture

```bash Terminal
minicut gen image lin-xia.png --prompt-file lin-xia.txt --model MODEL --target character:lin-xia --project rain-shop
```

Replace `MODEL` with a name from the list. This sends nothing until you say yes.

### Output

Without `--yes`, the command says `Nothing was sent.` and prints the line to run after your yes. With `--json` it prints `"state": "needs_yes"` and that line as `next_step`. With the `--yes` line, it sends the job and prints its job id.

### See also

[minicut jobs](#minicut-jobs), [minicut models](#minicut-models), [minicut save](/docs/cli/projects#minicut-save)

## minicut gen video

Makes one video take for a shot, from the shot's own folder.

### Usage

```text Usage
minicut gen video CLIP_FOLDER [--again] [--reason REASON] [--name NAME] [--json]
```

Replace the following:

- `CLIP_FOLDER`: the shot's folder, such as `episodes/ep01/clips/c03`.
- `REASON`: a few words on why you make this take.
- `NAME`: the short name people read on the take.

### Details

The command reads the shot's settings, prompt and pictures from its folder. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. It sends the job and returns, and [minicut jobs](#minicut-jobs) saves the take into the shot's folder.

One shot has one job at a time. If the shot already has a job queued or running, the command stops and names that job. Stop it first, or add `--again` to make another take beside it.

If you make a video take before the Mock loop is approved, the command prints a warning and records it. It does not refuse. See [Checks and loops](/docs/cli/checks-and-loops).

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--again` | switch | off | Make another take while the shot already has a job |
| `--reason` | text | none | Why you make this take |
| `--name` | text | none | The name people read on the take |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Make a take for shot 3

```bash Terminal
minicut gen video episodes/ep01/clips/c03
```

### Output

The same as [minicut gen image](#minicut-gen-image): the `--yes` line first, then the job id after your yes.

### Errors

| Message | What to do |
|---|---|
| `Shot <shot> already has job <job> <state>.` | Stop it with `minicut jobs --stop <job>`, or add `--again` |
| `no clip.json in <folder>` | Give the path to a shot folder in an episode |

### See also

[minicut jobs](#minicut-jobs), [minicut check take](/docs/cli/checks-and-loops#minicut-check-take)

## minicut gen voice

Makes one spoken line for the mock, saved in the shot's folder.

### Usage

```text Usage
minicut gen voice OUT_FILE --text-file TEXT_FILE --voice VOICE --target line:CLIP-N --project PROJECT [--episode EPISODE] [--model MODEL] [--json]
```

Replace the following:

- `OUT_FILE`: the sound file to make, such as `l01.mp3`.
- `TEXT_FILE`: a text file with the words to speak.
- `VOICE`: a voice name. `minicut voices` lists the voices a voice model takes.
- `CLIP-N`: the shot and the line number, such as `c03-1`.
- `PROJECT`: a project id or the path to a project folder.
- `EPISODE`: an episode id such as `ep01`.
- `MODEL`: a voice model name from [minicut models](#minicut-models).

### Details

This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. The finished line is saved in the shot's folder, under `lines/`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--text-file` | file | none | The words to speak. Needed |
| `--voice` | name | none | The voice. Needed |
| `--target` | `line:CLIP-N` | none | The shot and line. Needed |
| `--project` | id or folder | none | The project. Needed |
| `--episode` | episode id | none | The episode of the shot |
| `--model` | name | the project's voice model | The voice model |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Make line 1 in shot 3

```bash Terminal
minicut gen voice l01.mp3 --text-file line.txt --voice VOICE --target line:c03-1 --project rain-shop --episode ep01
```

Replace `VOICE` with a voice name.

### See also

[minicut gen batch](#minicut-gen-batch), [minicut jobs](#minicut-jobs)

## minicut gen MODEL

Runs any other model by its name: music, sound split, lip sync, upscale, clip repair and 3D.

### Usage

```text Usage
minicut gen MODEL OUT_FILE [--prompt PROMPT | --prompt-file PROMPT_FILE] [--set SETTING=VALUE ...] [--in INPUT=FILE ...] --target KIND:ID [--project PROJECT] [--episode EPISODE] [--name NAME] [--json]
```

Replace the following:

- `MODEL`: a model name from [minicut models](#minicut-models).
- `OUT_FILE`: the file to make.
- `PROMPT`: the words for the model, in quotes.
- `PROMPT_FILE`: a text file with the words for the model.
- `SETTING=VALUE`: one setting the model lists, such as `seconds=8`. Repeat it for more.
- `INPUT=FILE`: one input file the model takes. Repeat it for more.
- `KIND:ID`: what the file is for. `KIND` is `character`, `location`, `prop`, `style` or `canvas`.

### Details

`minicut models MODEL` lists the settings and inputs a model takes. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--prompt` | text | none | The words for the model |
| `--prompt-file` | file | none | A file with the words for the model |
| `--set` | `SETTING=VALUE` | the model's own | One setting. Repeat it for more |
| `--in` | `INPUT=FILE` | none | One input file. Repeat it for more |
| `--target` | `KIND:ID` | none | What the file is for. Needed |
| `--project` | id or folder | none | The project |
| `--episode` | episode id | none | The episode |
| `--name` | text | none | The name people read on the asset card |
| `--json` | switch | off | Print one JSON object |

### See also

[minicut models](#minicut-models), [minicut jobs](#minicut-jobs)

## minicut gen batch

Sends many `gen` commands and asks once for all of them.

### Usage

```text Usage
minicut gen batch LIST_FILE [--no-wait] [--json]
```

Replace the following:

- `LIST_FILE`: a text file with one `gen` command a line, written without `minicut gen` in front.

### Details

Each line is `image ...`, `voice ...` or `video CLIP_FOLDER`, with its flags. Leave `--yes` out of every line. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question.

The `--yes` line sends the items one at a time. When your account has no free slot, it waits up to 9 minutes for one, and nothing is sent while it waits. Running the same `--yes` line again never sends an item twice. A shot can appear on one line only, unless that line has `--again`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--no-wait` | switch | off | Stop at once when there is no free slot, instead of waiting |
| `--json` | switch | off | Print JSON |

### Examples

#### Make three pictures and two takes at once

```text shots.txt
image lin-xia.png --prompt-file lin-xia.txt --model MODEL --target character:lin-xia --project rain-shop
image shop.png --prompt-file shop.txt --model MODEL --target location:shop --project rain-shop
image umbrella.png --prompt-file umbrella.txt --model MODEL --target prop:umbrella --project rain-shop
video episodes/ep01/clips/c01
video episodes/ep01/clips/c02
```

```bash Terminal
minicut gen batch shots.txt
```

### Output

Without `--yes`, one line per item, then `Nothing was sent.` and the `--yes` line. With the `--yes` line, one result per item, then how many of them were sent.

### See also

[minicut jobs](#minicut-jobs)

## minicut jobs

Lists your open jobs and saves the finished ones into your project.

### Usage

```text Usage
minicut jobs [--wait SECONDS] [--json]
minicut jobs --get JOB_ID [--json]
minicut jobs --stop JOB_ID [--json]
```

Replace the following:

- `SECONDS`: how long to keep checking, in seconds.
- `JOB_ID`: the id of one job, as `minicut jobs` lists it.

### Details

`minicut gen` and `minicut board run` send jobs and do not wait for them. `minicut jobs` reads every open job on your account. It saves each finished result into the project or board it was made for, and lists the rest by id. A job made for a project that is not on this computer is listed and left open.

`--wait` keeps checking until every job it can save is saved, or the time runs out. `--get` saves one job here, even when it was already saved. `--stop` stops one job.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--wait` | seconds | none | Keep checking for up to this long |
| `--get` | job id | none | Save this job here |
| `--stop` | job id | none | Stop this job |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Save finished jobs, waiting up to 5 minutes

```bash Terminal
minicut jobs --wait 300
```

### Output

One line per job: `job <id>: saved <files>`, or its state, such as `running`. A failed job prints `failed`, its error code, and a `Why:` line with the reason. Exit codes: 0 when nothing failed, 6 when `--wait` ran out with a job still running, 7 when minicut.ai did not answer. A failed job exits with its own code, listed on [Global options](/docs/cli/global-options).

### See also

[minicut gen image](#minicut-gen-image), [minicut shots](/docs/cli/projects#minicut-shots)

## minicut models

Lists the models you can use, or shows one model's settings.

### Usage

```text Usage
minicut models [--kind KIND] [--search WORDS] [--json]
minicut models MODEL [--json]
```

Replace the following:

- `KIND`: one of `image`, `video`, `voice`, `audio`, `music`, `sfx`, `lipsync`, `upscale`, `videofx`, `audiofx` or `mesh3d`.
- `WORDS`: words to search model names for.
- `MODEL`: one model's name.

### Details

The list comes from minicut.ai and is saved on this computer. Offline, the command prints the saved list with its age. `--kind audio` lists the voice models and every music and sound model.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--kind` | kind | all | List one kind of model |
| `--search` | words | none | List the models whose names match |
| `--json` | switch | off | Print JSON |

### Examples

#### List the video models

```bash Terminal
minicut models --kind video
```

### Output

One line per model: its name, kind and status. `minicut models MODEL` prints that model's settings and page. Exit codes: 0 when it listed the models, 7 when it printed the saved list because minicut.ai did not answer.

### See also

[minicut gen MODEL](#minicut-gen-model)

## minicut write

Writes words for a text box with a writing model.

### Usage

```text Usage
minicut write TEXT [--model MODEL] [--json]
```

Replace the following:

- `TEXT`: what to write, in quotes.
- `MODEL`: a writing model name.

### Details

This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. With no `--model`, it uses the default writing model. A name the account does not have is refused, with the names it does have.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--model` | name | the default writing model | The writing model |
| `--json` | switch | off | Print one JSON object with `text` and `model` |

### Examples

#### Ask for a one-line title

```bash Terminal
minicut write "A one-line title for a rainy night shop drama"
```

### Output

After your yes, the command prints the words. Exit code 3 means it is waiting for your yes.

### See also

[minicut board](#minicut-board)

## minicut board

Makes, edits, checks and runs a canvas board, which is a file you edit.

### Usage

```text Usage
minicut board new [--project PROJECT --episode EPISODE] [--title TITLE] [--json]
minicut board check FILE [--json]
minicut board run FILE {--box BOX ... | --all} [--wait SECONDS] [--json]
minicut board add FILE --kind KIND [--id BOX] [--x N --y N] [--label LABEL] [--prompt PROMPT] [--model MODEL] [--parent BOX]
minicut board move FILE --box BOX --x N --y N
minicut board set FILE --box BOX [--label LABEL] [--prompt PROMPT] [--text TEXT] [--model MODEL] [--seconds N] [--file PATH] [--fields JSON]
minicut board {connect|disconnect} FILE --from BOX --to BOX
minicut board delete FILE --box BOX [--box BOX ...]
minicut board view FILE --view {workflow|storyboard}
minicut board retype FILE --box BOX --kind {character|location|prop}
```

Replace the following:

- `FILE`: the board file.
- `PROJECT`, `EPISODE`: the project and episode the board belongs to.
- `TITLE`: the board's title.
- `BOX`: a box id on the board.
- `KIND`: the kind of box, such as `image`, `video` or `character`.
- `N`: a number: a position, or a length in seconds.
- `PATH`: a file in the board's folder.
- `JSON`: several fields at once, as JSON.

### Details

The board file holds the boxes and the wires between them. Each edit command changes the file the same way the open **画布** tab in the MiniCut app does, and the open tab redraws by itself.

- `new` makes an empty board. With `--project` and `--episode` it goes in the episode's `canvas` folder. Without them it goes in its own folder in your MiniCut home folder.
- `check` reads the board for problems. It finds boxes with the same id, wires to missing boxes, wires that are not allowed, and missing upload files.
- `run` makes the listed boxes. It uses credits. It shows what it will do and asks once for all the boxes; `--yes` skips the question. A box that is refused keeps its reason on the board, and the other boxes still go. `--wait` saves the results into the board's folder.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--project` | id or folder | none | `new`: the project of the board |
| `--episode` | episode id | none | `new`: the episode of the board |
| `--title` | text | none | `new`: the board's title |
| `--box` | box id | none | The box to change or run. Repeat it for more in `run` and `delete` |
| `--all` | switch | off | `run`: every box that can run |
| `--wait` | seconds | none | `run`: wait this long and save the results |
| `--kind` | kind | none | `add`, `retype`: the kind of box |
| `--id` | box id | a new id | `add`: the new box's id |
| `--x`, `--y` | number | none | `add`, `move`: the box's position |
| `--label` | text | none | `add`, `set`: the box's label |
| `--prompt` | text | none | `add`, `set`: the box's words for its model |
| `--text` | text | none | `set`: the words in a text box |
| `--model` | name | none | `add`, `set`: the box's model |
| `--seconds` | number | none | `set`: the box's length |
| `--file` | path | none | `set`: a file in the board's folder for the box to show |
| `--fields` | JSON | none | `set`: several fields at once |
| `--parent` | box id | none | `add`: the group box to put the new box in |
| `--from`, `--to` | box id | none | `connect`, `disconnect`: the two ends of the wire |
| `--view` | `workflow` or `storyboard` | none | `view`: how the board is laid out |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Make a board for episode 1

```bash Terminal
minicut board new --project rain-shop --episode ep01 --title "Opening"
```

#### Make every box on a board

```bash Terminal
minicut board run episodes/ep01/canvas/opening.board.json --all
```

### Output

`check` prints `Board ok:` with the number of boxes and wires, or one line per problem. Each edit prints `Board <command>: ok` with the board's new revision number, and the new box id after `add`.

| Exit code | Meaning |
|---|---|
| 0 | It worked |
| 1 | The board has a problem, or the edit is refused |
| 2 | A flag is missing |
| 3 | `run` is waiting for your yes |

### See also

[minicut jobs](#minicut-jobs), [minicut write](#minicut-write)