@shop-os/modelkit 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -9,6 +9,67 @@ header in the release PR.
 
 ## [Unreleased]
 
+## [0.2.21] - Unreleased
+
+### Added
+- `capabilities.lastFrameRequiresFirstFrame` (boolean): a video row that takes an end frame only together with a start frame. On such a row, `resolveVideoOptions` in `error` mode refuses an end frame without a start frame with a non-retryable `missing_input`; in `coerce` mode the lone end frame becomes the start frame, with an `option_ignored` warning ("end frame used as start frame: <model> needs a start frame with an end frame"). Set on `veo-3.1` ("must be used in combination with the image parameter") and `gemini-omni-1.1-flash` (`<LAST_FRAME>` "must be used with `<FIRST_FRAME>`"). Not set on `kling-v3-omni-video` (`end_image` "Requires start_image"): error-mode callers get `missing_input`, and SpaceLab's vibe-triggers resolves replicate and google-genai rows in error mode, so the flag would refuse its end-frame-only Kling Omni nodes. Without the flag the Replicate adapter keeps sending a lone end frame as `start_image`.
+- `gemini-omni-1.1-flash` takes an end frame (`supports: ["videoExtension", "lastFrame"]`). The adapter sends the start image, then the end image, then any references, and prefixes the prompt with the docs' role tags `<FIRST_FRAME> <LAST_FRAME>`. A chained extension drops the end frame with a warning, as it drops the other conditioning media.
+- Higgsfield `kling-3.0` sound switch: `generateAudio` maps to the endpoint's `sound: "on" | "off"`. The row is now `audio: "optional"`, `supports` `generateAudio`, default `generateAudio: true` (the provider default is on).
+- `kling-v3-omni-video` offers `4k`: the Replicate adapter maps `resolution: "4k"` to `mode: "4k"` (4K does not take a reference video, which the adapter never sends).
+- `constraints.prompt.maxChars`: 2500 on `kling-2.5`, `kling-3.0` and `kling-v3-omni-video` (Higgsfield 3.0 truncates past 2,500; Replicate's Omni says "Max 2500 characters"; Higgsfield 2.5 documents none, the same model on fal and Kling's API caps it at 2,500), 3000 on `veo-3.1` (1,024 text tokens at about 2.9 characters per token; a CJK prompt can hit the token limit sooner). Each keeps its `numbered` reference syntax.
+
+### Changed
+- Higgsfield Kling adapter sends each endpoint only the fields its schema has. `kling-video/v2.5-turbo/pro/image-to-video` gets no `aspect_ratio` and no `last_image_url`; `kling-video/v3.0/pro/image-to-video` gets no `aspect_ratio` and no `negative_prompt`. A dropped caller value becomes an `option_ignored` warning. An unlisted Higgsfield Kling endpoint keeps the fields it was sent before.
+- `kling-2.5`: no `aspectRatios`, no ratio default, `supports` loses `lastFrame`.
+- `kling-3.0`: no `aspectRatios`, no ratio default, `supports` loses `negativePrompt` (and the default negative prompt).
+- `kling-v3-omni-video`: `aspectRatios` loses `adaptive` (not in Replicate's enum; "Auto" meant the provider's 16:9); `resolutions` gains `4k`; default `generateAudio: true`.
+- `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.5`: `supports` loses `seed`. BytePlus accepts and echoes `seed` on 2.x, but two identical seeded tasks gave different videos (SSIM 0.83, 2026-10-01). The ark adapter still sends `seed` for rows that support it (Seedream and others).
+- `seedance-2.5`: default `generateAudio: true` (sound on by default where it is optional).
+- `minimax-h3-max`, `minimax-h3-max-reference`: `resolutions` gain `1080p` (sent as fal's `1080P`).
+- `minimax-h3`, `minimax-h3-max`, `minimax-h3-reference`, `minimax-h3-max-reference`: `ratioIgnoredWith: ["firstFrame"]`. A start frame routes to fal's image-to-video endpoint, which has no `aspect_ratio`.
+- `grok-imagine`: `references.images` 7 (was 5); the xAI adapter caps at 7 ("A maximum of 7 reference images can be provided per request"). The description still says 5 because it is pinned to the Cowork catalog fixture.
+
+### Deferred
+- `veo-3.1` stays at `durations: [8]`. Veo also takes 4 s and 6 s, but must be 8 s at 1080p or 4k and with reference images, and the kit has no rule that forces a duration from other options. Offering `[4, 6, 8]` now would snap SpaceLab's stored Veo nodes (default 5 s) to 4 s, which Veo rejects at 1080p/4k and which halves 720p clips. Ship it with a kit rule that forces 8 s in those cases (`veo-3.1-fast` and `veo-3.1-lite` already list 4/6/8 and have this gap).
+
+### Live rows to edit after publish
+Apps read the pro-backend `model_catalog` rows, not this file. Before the live edit, add `credit_pricing_video` rows for `kling-v3-omni-video` at `4k` and for `minimax-h3-max` / `minimax-h3-max-reference` at `1080p`: without them those options fail to quote. At the version bump in shopos-ui, update vibe-api's pinned pricing producer contract (`contracts/backend-pricing-contract.json`, checked by `producer-contract.test.ts` against the bundled rows), which gains the same `kling-v3-omni-video`/`4k` and `minimax-h3-max`/`1080p` keys.
+
+Preconditions:
+- Remove the `kling-2.5` and `kling-3.0` aspect ratios only after cowork with Shop-OS/shopos-backend-ts#1197 (including its ratio-less projection fix) is deployed. Before that, #1197's `?frames=1` projection 500s on a ratio-less row.
+- Set `capabilities.lastFrameRequiresFirstFrame` through pro-backend's admin catalog API. Don't save the `veo-3.1` or `gemini-omni-1.1-flash` rows in pro-admin until its row form keeps unknown capability keys and has the checkbox (fix in Shop-OS/shopos-ui#2711); today it drops the whole `capabilities` object.
+
+Behaviour after the edit:
+- `seedance-2.5` and `kling-v3-omni-video` default to sound on, and chat and Creative Director send the row default, so their videos gain sound too. Credits are unchanged until audio pricing lands. Kling V3 Omni with audio costs $0.224/s at standard (720p) and $0.28/s at pro (1080p) on Replicate, against $0.168/s and $0.224/s without: check the `credit_pricing_video` margin.
+- A SpaceLab Kling 3.0 node with a stored `generate_audio: false` goes silent after the `kling-3.0` edit, where it had sound before.
+
+After pro-backend is on 0.2.21, in each environment:
+- `kling-2.5`: remove `constraints.aspectRatios`; remove `defaults.aspectRatio`; `constraints.supports` → `["cfgScale", "negativePrompt"]`; `constraints.prompt` → `{ "referenceSyntax": "numbered", "maxChars": 2500 }`; `display.description` → the new text (no end image).
+- `kling-3.0`: remove `constraints.aspectRatios`; remove `defaults.aspectRatio` and `defaults.negativePrompt`; `constraints.supports` → `["cfgScale", "lastFrame", "generateAudio"]`; `constraints.audio` → `"optional"`; `defaults.generateAudio` → `true`; `constraints.prompt` → `{ "referenceSyntax": "numbered", "maxChars": 2500 }`. Higgsfield lists this endpoint at $0.112-$0.168/s without labelling the sound split; check whether `credit_pricing_video` should price sound on and off separately.
+- `kling-v3-omni-video`: `constraints.aspectRatios` → `["16:9", "9:16", "1:1"]`; `constraints.resolutions` → `["720p", "1080p", "4k"]`; `defaults.generateAudio` → `true`; `constraints.prompt` → `{ "referenceSyntax": "numbered", "maxChars": 2500 }`; `display.description` → "... up to 4K". Needs a `credit_pricing_video` row for `kling-v3-omni-video` at `4k` first (Replicate: $0.42/s, with or without audio).
+- `veo-3.1`: `constraints.prompt` → `{ "referenceSyntax": "numbered", "maxChars": 3000 }`; `capabilities.lastFrameRequiresFirstFrame` → `true`.
+- `gemini-omni-1.1-flash`: `constraints.supports` → `["videoExtension", "lastFrame"]`; `capabilities.lastFrameRequiresFirstFrame` → `true`.
+- `seedance-2.0`, `seedance-2.0-fast`: `constraints.supports` → `["generateAudio", "lastFrame", "watermark"]`.
+- `seedance-2.5`: `constraints.supports` → `["generateAudio", "lastFrame", "watermark", "taskType"]`; `defaults.generateAudio` → `true`.
+- `minimax-h3`, `minimax-h3-reference`: `constraints.ratioIgnoredWith` → `["firstFrame"]`.
+- `minimax-h3-max`, `minimax-h3-max-reference`: `constraints.resolutions` → `["480p", "768p", "1080p"]`; `constraints.ratioIgnoredWith` → `["firstFrame"]`; `display.description` of `minimax-h3-max` → "... up to 1080p". Needs `credit_pricing_video` rows for both at `1080p`.
+- `grok-imagine`: `constraints.references.images` → `7`.
+- `p-video-2-pro` (pro-admin-only, not in this file): `constraints.aspectRatios` without `adaptive` (Replicate's enum has none); `constraints.audio` → `"always"` (still outstanding from 0.2.20).
+
+## [0.2.20] - Unreleased
+
+### Added
+- `constraints.audio` (`"always" | "optional" | "never"`): whether a video row's output has sound. Every video row sets it; `supports: ["generateAudio"]` still means only that sound can be switched. Read it with `outputAudio(row)`.
+- `constraints.prompt` (`{ referenceSyntax: "numbered" | "caption" | "descriptive"; maxChars? }`): how a prompt should point at reference N. Gemini image rows and the Gemini Omni rows use `caption` (their adapters send `MediaRef.label`); every other row reads as `numbered`. Read it with `promptConventions(row)`.
+- Both keys are strict on write (`CatalogModelSchema`, pro-backend's pro-admin validation) and tolerant on read: `load.ts` keeps a row with an invalid value and the accessors read it as not set.
+- On read, `load.ts` removes an invalid `constraints.audio` and normalises an invalid `constraints.prompt` (with one warning per row), so a loaded row never carries an invalid value typed as valid. `CatalogSchema` normalises the same way (via `normaliseConventions`, exported from `conventions.ts`); the write schema `CatalogModelSchema` stays strict.
+
+### Fixed
+- `minimax-h3-reference` / `minimax-h3-max-reference`: `capabilities.framesExcludeReferences: true`. A start frame sent with references was silently lost (fal's reference-to-video endpoint ignores frames); the resolver now keeps the frame and drops the references with a warning (coerce) or rejects the pair (error).
+- `flux-2-pro`: `references.images: 8`. The row declared no limit, so every reference reached Prodia.
+
+Mirror every row change on the pro-backend `model_catalog` rows in each environment, after pro-backend is on 0.2.20 (apps read the rows, not this file), and set `constraints.audio: "always"` on the pro-admin-only `p-video-2-pro` row.
+
 ## [0.2.19] - Unreleased
 
 ### Changed