@shop-os/modelkit 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -9,6 +9,25 @@ header in the release PR.
 
 ## [Unreleased]
 
+## [0.6.1] - Unreleased
+
+### Fixed
+- Every Replicate Kling row (kind `kling` or `kling-omni`, today `kling-v3-omni-video`): the resolved request keeps only the `resolution` that renders and drops `mode`. A 720p request no longer carries the row default `mode: "pro"` next to it. A request without a resolution takes its `mode`'s (`standard` 720p, `pro` 1080p; neither: 720p) before the resolution check, so a row that does not list that resolution refuses it (`error`) or coerces it with a `resolution_coerced` warning (`coerce`). What the provider receives for an accepted request is unchanged.
+
+## [0.6.0] - Unreleased
+
+### Added
+- `model3d` model type: a prompt and/or photos of an object in, a GLB out. Seven fal rows (`trellis-2`, `hunyuan3d-3.1-pro`, `tripo-h3.1`, `rodin-gen-2.5`, `meshy-7.1`, `hi3d-3.0`, `sam-3d-objects`), `exposure: ["space_builder"]`. What each takes is data on `constraints.model3d` (family, endpoints, text, required image or prompt, views, texture, PBR, seed, resolutions); the catalog schema requires it on every `model3d` row and rejects a spec its family's request mapping could not run or price (a missing endpoint for a request it accepts, views, texture, PBR, seed or resolution options the family does not read or needs).
+- `ModelKit.submitModel3d` / `model3dStatus` / `model3dResult` / `cancelModel3d` (fal adapter): a resumable queue job like the video tools, with the same pinned queue origin, webhook and key tiers. Inputs a row cannot run are refused before submit.
+- `model3dInputRefusal`, `model3dPricingSku`, `model3dSkus`, `model3dTexture`, `model3dResolution`, `model3dConstraints`, `MODEL3D_IMAGE_SLOTS` and `MODEL3D_MODELS`, also on the browser-safe `@shop-os/modelkit/catalog` entry. A 3D request bills one flat price per option combination (its SKU), not per model id.
+- `Model3dRequest.views.top` (and `Model3dWired.top`): a fifth photo, sent only by `unordered` rows, so Rodin Gen-2.5 takes the five images fal's `image_urls` allows (Meshy sends the first four set; named and ordered rows have no slot for it). `MODEL3D_IMAGE_SLOTS` lists the slots the request mapping fills per views kind, and the catalog schema refuses a `maxImages` above that count.
+- `UsageUnit` `"requests"`: one call billed at a flat price, the usage sink's `REQUESTS`. The `model3d` rows and their usage events use it (a 3D job is one flat-priced request, not an image). Kits before 0.6.0 quarantine rows with this unit.
+- `constraints.model3d.seedMax` and `model3dSeedFits(spec, seed)`: the largest seed a row's provider takes (Rodin Gen-2.5: 65535, fal's limit; absent means any non-negative integer). `submitModel3d` refuses a seed outside it as `unsupported_option` before submit, and the catalog schema refuses `seedMax` on a row without `seed`.
+- The 3D adapter accepts only https GLB and thumbnail URLs in a result (stored or webhook); any other scheme is a `provider_rejected` `ModelKitError`, never passed through.
+
+### Changed
+- The fal queue helpers moved from `fal-video-tools.ts` to `fal-queue.ts`, shared by video tools and 3D. `falWebhookBodySchema` and `FalWebhookBody` are still exported from the package root.
+
 ## [0.5.0] - Unreleased
 
 ENG-3271: the latest fal / Prodia models for the catalog and the Sloosh canvas.

package/README.md

@@ -83,6 +83,31 @@ const out = await kit.videoToolResult(sub, { webhook: verifiedBody }); // or pol
 `source` carries the caller's measured `width`, `height`, `durationSeconds` and `fps`; the kit
 never measures. Verifying the webhook signature is the caller's job.
 
+### 3D models
+
+`model3d` rows (Trellis 2, Hunyuan3D, Tripo, Rodin, Meshy, Hi3D, SAM 3D on fal) take a prompt
+and/or photos of an object and return a GLB. They run as provider jobs too, the same way:
+
+```ts
+const sub = await kit.submitModel3d({ model: "tripo-h3.1", image, views: { left, back, right } });
+// store `sub` (plain JSON); later: model3dStatus(sub), model3dResult(sub), cancelModel3d(sub)
+const out = await kit.model3dResult(sub); // out.glb.url, out.thumbnail?.url, out.sku
+```
+
+What a row takes (text, required image or prompt, views, texture, PBR, seed, a priced
+resolution) is data on `constraints.model3d`; the adapter picks the fal endpoint and builds the
+body per `family`. The catalog schema checks a spec against what its family's mapping reads
+(the endpoints a request it accepts goes to, its views, texture, PBR, seed and resolution
+options, and a `maxImages` no larger than the image slots it sends: `MODEL3D_IMAGE_SLOTS`, 5 for
+`unordered` views with `views.top` as the fifth, 4 for `named` and `ordered`), so a row the
+adapter could not run or price is rejected on load and on write. The result's GLB and thumbnail
+URLs are https or the call fails (`provider_rejected`), and the usage event is one request
+(`unit: "requests"`), billed at the flat price of its SKU.
+`model3dInputRefusal(spec, wired)` says why inputs cannot run (also checked
+before submit), and `model3dPricingSku(row, options, inputs)` names the flat price a request
+bills under; `model3dSkus(row)` lists them all, and pro-backend keeps a `credit_pricing_flat`
+row for each. All three are in the browser-safe catalog entry.
+
 Keys come from `process.env` by default: bare names for pro (`OPENAI_API_KEY`, `FAL_KEY`, `ARK_API_KEY` ...), the `ENTERPRISE_` prefix for enterprise and the `SLOOSH_` prefix for sloosh. Pass `keys: { pro, enterprise, sloosh }` to override. `tier: "sloosh"` uses the sloosh keys only: a missing key is a `ModelKitError` with code `auth`, never a fallback to pro.
 
 ## Browser-safe catalog
@@ -288,7 +313,7 @@ const defaultKit = createDefaultModelKit({ keys: { pro: keysFromEnv(process.env)
 
 ## Add a model
 
-1. Add a row to `src/catalog/{image,video,video-families,video-tools,text,other}.ts`. A new fal
+1. Add a row to `src/catalog/{image,video,video-families,video-tools,model3d,text,other}.ts`. A new fal
    video family gets its own mapper file (`src/adapters/fal-<family>.ts`) listed in
    `fal-video-families.ts`, which is what makes its exact ids pass the data-only check. Copy `constraints` from the provider docs.
 2. Run `pnpm test`. The catalog test checks id and alias uniqueness.