fimo 0.7.0-experimental.2 → 0.7.0-experimental.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -49,7 +49,8 @@ Manage content, schemas, media, and labels from the CLI:
49
49
  ```bash
50
50
  fimo schemas push # sync your content models
51
51
  fimo entries list # browse content
52
- fimo assets upload <file> # add media (or `fimo assets generate` with AI)
52
+ fimo assets upload <file> # add existing media
53
+ fimo image generate --prompt "..." # create an image with AI
53
54
  fimo labels list # manage labels and localized copy
54
55
  ```
55
56
 
@@ -58,7 +58,7 @@ Workflow / CLI-side concerns (pushing schemas, generating images, managing label
58
58
  - **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
59
59
  - **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
60
60
  - **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
61
- - **Pulling stock photos from external URLs** — editors can't manage them. Use `fimo generate` (CLI).
61
+ - **Pulling stock photos from external URLs** — editors can't manage them. Use a Fimo media task such as `fimo image generate`.
62
62
  - **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerate them through `fimo validate` or the matching push command.
63
63
  - **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.
64
64
  - **Calling `t()` with a dynamic first argument** — the key must be a string literal so the extractor finds it.
@@ -1,12 +1,12 @@
1
1
  # Assets — package surface
2
2
 
3
- > For the CLI commands (`fimo assets upload`, `fimo generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
3
+ > For the CLI commands (`fimo assets upload`, `fimo image generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
4
4
 
5
5
  This file covers the **package surface** for working with assets in code: the `media` field value shape, how to render assets with `fimo/ui` components, the URL format.
6
6
 
7
7
  ## `media` field value (stored/wire shape)
8
8
 
9
- Asset values returned from `fimo assets upload` or `fimo generate`, and stored in `media` content-type fields:
9
+ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored in `media` content-type fields:
10
10
 
11
11
  ```json
12
12
  {
@@ -176,7 +176,7 @@ Always provide a meaningful `slug` when creating an entry — it appears in URLs
176
176
  - **Stable** — once an entry is live, changing the slug breaks inbound links. Only update intentionally.
177
177
  - If you omit `slug`, the backend generates a random one — never rely on this for content you want to link to.
178
178
 
179
- For `media` fields, prefer `source: "local"` with assets uploaded via `fimo assets upload` or generated via `fimo generate` (see `fimo-cli/assets.md`).
179
+ For `media` fields, prefer `source: "local"` with assets uploaded via `fimo assets upload` or generated with a Fimo media task such as `fimo image generate` (see `fimo-cli/references/media.md`).
180
180
 
181
181
  ## Generated React Query hooks
182
182
 
@@ -124,7 +124,7 @@ Write into `src/index.css` as shadcn CSS variables, then use `bg-background` / `
124
124
  - **Treatment:** Full-bleed, contained, overlays, filters
125
125
  - **Hero:** Specific direction for hero imagery
126
126
 
127
- If the user hasn't supplied images and one is needed, generate via `fimo generate <model> --prompt "..."` (run `fimo models list` to pick a model, `fimo models show <model>` for its flags) and reuse the returned `url` / `id`. See `references/assets.md`.
127
+ If the user hasn't supplied images and one is needed, run `fimo image generate --prompt "..."` and reuse the returned `url` or `id`. Run `fimo image generate --help` for current flags. See `references/assets.md`.
128
128
 
129
129
  ### Iconography
130
130
 
@@ -73,7 +73,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
73
73
  - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo/references/forms.md` for the JSON spec and generated client**
74
74
  - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
75
75
  - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo/references/assets.md` for the `FimoMedia` shape and rendering**
76
- - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (the `fimo generate <model>` surface — recipes, defaults, the one-verb shape) **+ load `fimo/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
76
+ - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
77
77
  - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo/references/labels.md` for the `t()` helper and wrap rules**
78
78
  - "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo/references/locales.md` for code helpers**
79
79
  - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
@@ -3,7 +3,7 @@
3
3
  > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
4
4
 
5
5
  > For how to plug returned media into UI components (`FimoMedia` shape, `<Image>` integration), see **`fimo/references/assets.md`** and **`fimo/references/ui.md`**.
6
- > For **generating** new images / videos with AI, see **`references/media.md`** — the `fimo generate <model>` surface is documented there.
6
+ > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
7
7
 
8
8
  This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
9
9
 
@@ -39,15 +39,15 @@ Use `--folder-path` when an agent needs a non-interactive upload target and does
39
39
 
40
40
  ## Generate AI media
41
41
 
42
- Moved to **`references/media.md`**. The generation surface is one verb:
42
+ Moved to **`references/media.md`**. Choose the task that describes the outcome:
43
43
 
44
44
  ```bash
45
- fimo generate <model-id-or-shortname> [--flag value ...]
45
+ fimo image generate --prompt "<prompt>"
46
+ fimo image edit --prompt "<instruction>" --images <asset-id-or-url>
47
+ fimo video generate --prompt "<prompt>"
46
48
  ```
47
49
 
48
- Per-model flags come from the API. `fimo models list` lists models;
49
- `fimo generate <model> --help` lists that model's flags. See `media.md` for
50
- the recipes block and the default-pick table.
50
+ Task flags come from the API. Run `fimo <namespace> <task> --help` for the current options. Fimo owns the internal generation route.
51
51
 
52
52
  ### When to prefer generation over uploads / placeholders
53
53
 
@@ -59,23 +59,6 @@ the recipes block and the default-pick table.
59
59
  - The user has already uploaded or referenced a specific file.
60
60
  - The image must be a real photo of a real thing (team photos, real product shots).
61
61
 
62
- ## Browse models — `fimo models`
63
-
64
- ```bash
65
- fimo models list # all, grouped by modality
66
- fimo models list --modality image # filter by modality
67
- fimo models list --tag draft --tag fast # filter by tag (repeatable, AND)
68
- fimo models list --provider pruna # filter by provider
69
- fimo models list --json # machine-readable
70
- fimo models show pruna/p-image # full detail + per-flag schema
71
- fimo models show gpt-image-2 --json # JSON dump (for agents)
72
- ```
73
-
74
- Model selection is **not** persisted per project. Picks live in
75
- `media.md` (baseline) → `CLAUDE.md` / `AGENTS.md` (project policy) → the
76
- prompt itself (highest priority). To target a specific model, name it on the
77
- command: `fimo generate <model> …`.
78
-
79
62
  ## Browse the library — `fimo assets list`
80
63
 
81
64
  ```bash
@@ -144,6 +127,6 @@ fimo assets delete <asset-id>
144
127
 
145
128
  ## End-to-end workflow
146
129
 
147
- 1. Upload (`fimo assets upload`) OR generate (`fimo generate <model> ...`) the asset.
130
+ 1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
148
131
  2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
149
132
  3. To use in JSX, see `fimo/references/ui.md` — schema media → `<Image>` / `<Video>`, hardcoded URLs → `<StaticImage>`. **Never** use raw `<img src={asset.url}>`.
@@ -11,7 +11,7 @@ This file covers the **CLI workflow** for content. Use it when the user wants to
11
11
  1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). For the JSON shape and field types, load `fimo/references/content.md`.
12
12
  2. Run `fimo schemas push {Uid}`. It generates `src/schemas/{Uid}.types.ts` and `src/schemas/{Uid}.ts`, then registers the schema with Fimo. It does not run whole-project validation.
13
13
  3. App code imports the generated client from `@/schemas/{Uid}`, not from `.types.ts` directly. See `fimo/references/content.md` for the hook API.
14
- 4. Seed entries via `fimo entries create`. Generate cover images first with `fimo generate <model>` if needed (see `media.md` / `assets.md`).
14
+ 4. Seed entries via `fimo entries create`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
15
15
  5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
16
16
 
17
17
  Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
@@ -108,7 +108,7 @@ Use `"isSingleton": true` for a type with exactly one logical document. Generate
108
108
  1. Load `fimo/references/content.md` for the JSON shape and field types.
109
109
  2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
110
110
  3. Run `fimo schemas push BlogPost`.
111
- 4. Generate cover images: `fimo generate pruna/p-image --prompt "..."` (per-model flags come from `fimo models show <model>`; see `media.md`).
111
+ 4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
112
112
  5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
113
113
  6. Load `fimo/references/ui.md` for the `<Text>`, `<Image>`, `<RichText>` components.
114
114
  7. Load `fimo/references/labels.md` for wrapping labels in `t()`.
@@ -1,181 +1,171 @@
1
- # Media generation
1
+ # AI media tasks
2
2
 
3
- > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
3
+ > **Run via `npx fimo@latest <command>`** so the task catalog and CLI stay aligned.
4
4
 
5
- > For uploading existing files, browsing the library, and opening assets, see
6
- > `references/assets.md`. This file is **only** about generating new media
7
- > via AI — the `fimo generate <model>` surface.
8
-
9
- The CLI exposes **one verb** for all media generation. The model is positional;
10
- every other input is a flag declared by that model's schema.
5
+ Use task commands for AI media. The command describes the outcome; Fimo chooses and can change the underlying generation route without changing agent instructions.
11
6
 
12
7
  ```bash
13
- fimo generate <model-id-or-shortname> [--flag value ...] [--json] [--dry-run]
8
+ fimo image generate --prompt "<prompt>"
9
+ fimo image edit --prompt "<instruction>" --images <asset-id-or-url>
10
+ fimo image remove-background --image <asset-id-or-url>
11
+ fimo image upscale --image <asset-id-or-url>
12
+
13
+ fimo video generate --prompt "<prompt>"
14
+ fimo video animate --video <asset-id-or-url> --image <asset-id-or-url>
15
+ fimo video replace --video <asset-id-or-url> --images <asset-id-or-url>
14
16
  ```
15
17
 
16
- `<model>` is either a canonical id (`pruna/p-image`) or its terminal-friendly
17
- shortName (`pruna-p-image`, `gpt-image-2`). The CLI fetches each model's flags
18
- and base price from the API (`GET /api/models`); the server validates the
19
- options. So flags, defaults, enum values, and pricing all come from one source
20
- and can't drift — `fimo models show <model>` prints them.
18
+ Use only task commands in new workflows. Internal routing details are not part of the public interface.
21
19
 
22
- ---
20
+ ## Shared behavior
23
21
 
24
- ## Models
22
+ - Run `fimo <namespace> <task> --help` for the current task flags.
23
+ - Add `--dry-run` to validate inputs and get a cost estimate without creating media.
24
+ - Add `--json` for structured output.
25
+ - Add `--name "..."` to set the media-library name.
26
+ - Add `--parent <folder-id>` to save into a folder.
27
+ - Source media can be a Fimo asset ID or an absolute URL.
28
+ - Repeat `--images` for tasks that accept multiple references.
29
+ - The response returns the created asset, cost, credits, task, and quality when applicable. Keep the asset `id` for content fields or the public `url` for direct use.
25
30
 
26
- Deliberately small, curated catalog (8 image + 3 video). This file documents the **defaults and recipes** below; for the live list with prices, tags, best-for, and flags, run `fimo models list --extended` (or `fimo models show <model>` for one model's options).
31
+ ## Quality
27
32
 
28
- ---
33
+ Tasks that expose `--quality` accept:
29
34
 
30
- ## Defaults — pick the cheapest model that does the job
35
+ - `draft`: faster and cheaper for iteration.
36
+ - `standard`: default for ordinary work.
37
+ - `premium`: higher quality for final, prominent media.
31
38
 
32
- **Default to `pruna/p-image` (images) and `pruna/p-video` (video).** The cheap baseline covers the large majority of requests. For anything it can't do — img2img edit, vector/SVG, background removal, upscale, virtual try-on, image-to-video — see the **Recipes** below; each names its model.
39
+ Start with `standard`. Use `draft` for disposable exploration. Use `premium` only when the user asks for the best result or the media is especially prominent.
33
40
 
34
- **Don't reach for the expensive models (`openai/gpt-image-2`, `fal-ai/bytedance/seedream`) unless explicitly asked** (e.g. a hero or other prominent image), or the project's `AGENTS.md` / `CLAUDE.md` sets a different default.
41
+ Preview the choice before spending credits:
35
42
 
36
- Model selection lives here (and in project `AGENTS.md` / `CLAUDE.md`). Run `fimo models list` for the live catalog, and
37
- **`fimo models show <model>` to read a model's options before you use it** —
38
- options are NOT standardized across models (e.g. pruna takes `--aspect-ratio`,
39
- while `gpt-image-2` / `seedream` size via `--image-size`). Don't assume a flag
40
- exists on a model you haven't inspected.
43
+ ```bash
44
+ fimo image generate \
45
+ --prompt "editorial illustration of a quiet coastal town at sunrise" \
46
+ --quality standard \
47
+ --aspect-ratio 16:9 \
48
+ --dry-run
49
+ ```
41
50
 
42
- ### Parameters for the default (pruna) models
51
+ ## Image recipes
43
52
 
44
- Inlined so you don't need `models show` for the common path. For **any other
45
- model**, run `fimo models show <model>` — its options will differ. (This list is
46
- a convenience snapshot; `models show` is the live source of truth.)
53
+ ### Generate an image
47
54
 
48
- **`pruna/p-image`** — text-to-image
55
+ ```bash
56
+ fimo image generate \
57
+ --prompt "editorial illustration of a quiet coastal town at sunrise" \
58
+ --quality standard \
59
+ --aspect-ratio 16:9 \
60
+ --name "Coastal sunrise hero"
61
+ ```
49
62
 
50
- - `--prompt <string>` · **required** · generation prompt
51
- - `--aspect-ratio <1:1|16:9|9:16|4:3|3:4>` · default `1:1`
63
+ Supported aspect ratios are `1:1`, `16:9`, `9:16`, `4:3`, and `3:4`.
52
64
 
53
- **`pruna/p-image-edit`** — img2img / prompt-driven edit
65
+ ### Edit one or more images
54
66
 
55
- - `--prompt <string>` · **required** · editing instruction
56
- - `--source-images <asset-id|url>` · **required** · repeatable, up to 5 (an `ast_*` asset id or an absolute URL)
57
- - `--aspect-ratio <1:1|16:9|9:16|4:3|3:4>` · default `1:1`
67
+ ```bash
68
+ fimo image edit \
69
+ --prompt "change the background to a warm sunset while preserving the subject" \
70
+ --images <asset-id-or-url> \
71
+ --aspect-ratio 16:9
72
+ ```
58
73
 
59
- **`pruna/p-video`** — text-to-video (add `--source-images` to do image-to-video)
74
+ Repeat `--images` to provide up to five references.
60
75
 
61
- - `--prompt <string>` · **required**
62
- - `--source-images <asset-id>` · optional · one `ast_*` asset id; passing it flips to image-to-video
63
- - `--aspect-ratio <1:1|16:9|9:16|4:3|3:4|3:2|2:3>` · default `16:9`
64
- - `--duration <int 1–10>` · default `5` (seconds)
65
- - `--resolution <720p|1080p>` · default `720p`
66
- - `--include-audio` · default off (pass the flag to enable)
76
+ ### Remove a background
67
77
 
68
- **`pruna/p-video-draft`** — same flags as `pruna/p-video`; ~4× cheaper, lower quality.
78
+ ```bash
79
+ fimo image remove-background --image <asset-id-or-url>
80
+ ```
81
+
82
+ ### Upscale an image
69
83
 
70
- ---
84
+ ```bash
85
+ fimo image upscale \
86
+ --image <asset-id-or-url> \
87
+ --target-megapixels 8 \
88
+ --output-format png \
89
+ --enhance-details
90
+ ```
71
91
 
72
- ## Recipes — user intent → exact command
92
+ Use `--enhance-realism` for photographic material. Use `--no-enhance-details` when preserving the original texture matters more than reconstruction.
73
93
 
74
- Each recipe is **one** command. The "Why" line tells the agent when to reach
75
- for this vs. an alternative.
94
+ ## Video recipes
95
+
96
+ ### Generate from text
76
97
 
77
98
  ```bash
78
- # "Generate an image" (default — cheapest workhorse)
79
- fimo generate pruna/p-image --prompt "<prompt>"
80
- # Why: fast, cheap, good enough for most cases.
81
-
82
- # "Generate a high-quality / typography / hero image"
83
- fimo generate openai/gpt-image-2 --prompt "<prompt>" --quality high
84
- # Why: premium quality, typography + realism. ~10–40× the baseline cost — use
85
- # only on an explicit request (e.g. hero / prominent media), never by default.
86
- # --quality low/medium saves cost (metered: ~$0.22 high → ~$0.02 low).
87
-
88
- # "Generate a 4K image" (native high resolution, no upscale needed)
89
- fimo generate fal-ai/bytedance/seedream/v4.5/text-to-image \
90
- --prompt "<prompt>" --image-size auto_4K
91
- # Why: outputs at 4K natively — skip the clarity-upscaler step.
92
-
93
- # "Edit an existing image with a prompt"
94
- fimo generate pruna/p-image-edit \
95
- --prompt "<edit instruction>" --source-images <asset-id-or-url>
96
- # Why: img2img with prompt-driven transforms. Style changes,
97
- # object swaps, scene relighting.
98
-
99
- # "Try a garment on a person" (e-commerce / fashion)
100
- fimo generate fal-ai/flux-pro/v1/vto \
101
- --prompt "<styling instruction>" \
102
- --human-image-url <person-url> --garment-image-url <garment-url>
103
- # Why: virtual try-on. Specific to fashion; don't use for general edits.
104
-
105
- # "Remove the background of an image"
106
- fimo generate fal-ai/bria/background/remove --source-images <image-url>
107
- # Why: deterministic transparent-PNG cutout. No prompt needed.
108
- # Note: this fal model takes an image URL, not a library asset-id.
109
-
110
- # "Upscale an image to higher resolution"
111
- fimo generate fal-ai/clarity-upscaler \
112
- --source-images <image-url> --upscale-factor 4
113
- # Why: 2×/3×/4× super-resolution. Best quality at 2×. Takes a URL, not an asset-id.
114
-
115
- # "Generate a vector illustration / SVG / icon"
116
- fimo generate fal-ai/recraft/v3/text-to-image \
117
- --prompt "<prompt>" --style vector_illustration/bold_stroke
118
- # Why: only model that returns SVG. Six style variants
119
- # (bold_stroke, line_art, cutout, infographical, marker_outline, seamless).
120
-
121
- # "Generate a video from text"
122
- fimo generate pruna/p-video --prompt "<prompt>" --duration 6 --aspect-ratio 16:9
123
- # Why: baseline video model. Add --include-audio for sound.
124
-
125
- # "Quick rough video preview"
126
- fimo generate pruna/p-video-draft --prompt "<prompt>" --duration 4
127
- # Why: ~4× cheaper than pruna/p-video. Same shape; switch to pruna/p-video for final.
128
-
129
- # "Generate a video from an existing image"
130
- fimo generate pruna/p-video \
131
- --prompt "<motion description>" --source-images <asset-id-or-url>
132
- # Why: same Pruna model — passing --source-images flips it to image-to-video mode.
133
-
134
- # "Cheap image-to-video alternative"
135
- fimo generate fal-ai/minimax/hailuo-02/standard/image-to-video \
136
- --prompt "<motion>" --source-images <image-url> --duration 6
137
- # Why: cheap i2v. Source is an image URL (not an asset-id); duration is 6 or 10.
138
- # Output aspect comes from the source image.
99
+ fimo video generate \
100
+ --prompt "slow camera push through a greenhouse after rain" \
101
+ --quality standard \
102
+ --duration 6 \
103
+ --aspect-ratio 16:9
139
104
  ```
140
105
 
141
- ---
106
+ Add `--include-audio` when the result should contain generated audio.
107
+
108
+ ### Generate from an image
109
+
110
+ ```bash
111
+ fimo video generate \
112
+ --prompt "subtle wind moves the leaves, locked camera" \
113
+ --image <asset-id-or-url> \
114
+ --duration 5 \
115
+ --aspect-ratio 16:9
116
+ ```
142
117
 
143
- ## Universal flags (every model)
118
+ ### Make a loop
144
119
 
145
- | Flag | Default | Meaning |
146
- | --------------------- | -------------- | ---------------------------------------------------------- |
147
- | `--name <str>` | slug of prompt | Asset display name in the library |
148
- | `--parent <asset-id>` | — | Library placement (folder asset-id) |
149
- | `-C, --cwd <dir>` | current dir | Project directory to resolve the env from |
150
- | `--json` | — | Machine-readable output (jq-friendly) |
151
- | `--dry-run` | — | Validate flags + show resolved request, don't call the API |
120
+ ```bash
121
+ fimo video generate \
122
+ --prompt "gentle water movement, seamless return to the first frame" \
123
+ --image <asset-id-or-url> \
124
+ --loop \
125
+ --duration 5
126
+ ```
152
127
 
153
- > Cost: there is no cost flag on `generate`. Pricing lives in discovery and is
154
- > shown as the provider's **per-unit rate** (e.g. `$0.045 / second`,
155
- > `$0.04 / image`), not a synthesized total. `fimo models list` shows the rate
156
- > per model; `fimo models show <model>` prints a `PRICING` block. With `--json`,
157
- > each model carries `price: { unitPrice, unit, confidence }` (or `null`). A `~`
158
- > prefix means even the rate is approximate (metered).
128
+ `--loop` requires `--image` and cannot be combined with `--include-audio`.
159
129
 
160
- ---
130
+ ### Transfer motion from a video to an image
161
131
 
162
- ## Discovery — read a model's options before you use it
132
+ ```bash
133
+ fimo video animate \
134
+ --video <motion-source-asset-id-or-url> \
135
+ --image <subject-image-asset-id-or-url> \
136
+ --quality standard \
137
+ --duration 5
138
+ ```
163
139
 
164
- Options are **not standardized across models** — each model declares its own
165
- flags. Before generating with a model you haven't used, read its options to
166
- understand what it can do (and what it expects): `fimo models show <model>`
167
- prints every flag with its type, default, enum values, description, and a usage
168
- example; `fimo generate <model> --help` prints the same flag list. Both come
169
- from the API (introspected server-side from the model's schema), so they can't
170
- drift. **Don't assume a flag carries across models** — e.g. `--aspect-ratio`
171
- exists on pruna but not on `gpt-image-2` / `seedream` (which size via
172
- `--image-size`).
140
+ ### Replace people in a video
173
141
 
174
142
  ```bash
175
- fimo generate openai/gpt-image-2 --help
176
- fimo models list --modality video
177
- fimo models list --tag draft # filter by tag (repeatable, AND semantics)
178
- fimo models list --extended # per-model card: alias, provider, tags, price, best-for, flags
179
- fimo models show fal-ai/flux-pro/v1/vto # PRICING rate + per-flag docs with usage examples
180
- fimo models show fal-ai/flux-pro/v1/vto --json # same, machine-readable (price.unitPrice / price.unit + flags)
143
+ fimo video replace \
144
+ --video <source-video-asset-id-or-url> \
145
+ --images <identity-image-asset-id-or-url> \
146
+ --quality standard \
147
+ --duration 5
181
148
  ```
149
+
150
+ Repeat `--images` for up to three identities. Add `--prompt` when placement needs clarification.
151
+
152
+ ## When to generate
153
+
154
+ Generate when the page needs original artwork, a hero, a card thumbnail, an avatar, an empty-state illustration, or a short motion asset and the user has not supplied one.
155
+
156
+ Do not generate when:
157
+
158
+ - the user supplied or named a specific asset;
159
+ - the result must depict a real person, team, product, or place accurately;
160
+ - an existing media-library asset already fits the request.
161
+
162
+ Upload real files with `fimo assets upload`. Browse reusable media with `fimo assets list` before spending credits.
163
+
164
+ ## Verification
165
+
166
+ After generation:
167
+
168
+ 1. Confirm the command exited successfully and returned an asset ID.
169
+ 2. Open or download the asset with `fimo assets open <id>`.
170
+ 3. Verify it matches the request before inserting it into content or UI.
171
+ 4. Use the whole media value with Fimo's `<Image>` or `<Video>` components rather than raw HTML elements.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "bundled": true,
3
3
  "bundler": "esbuild",
4
- "bundledAt": "2026-07-16T16:23:22.068Z",
4
+ "bundledAt": "2026-07-17T15:57:36.106Z",
5
5
  "cliVersion": "0.6.0",
6
6
  "external": [
7
7
  "oxc-parser",