@sogni-ai/sogni-client 5.19.5 → 5.21.0

package/AGENTS.md

@@ -71,7 +71,7 @@ Public chat and workflow media rules:
 
 ## Overview
 
-This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, Z-Image / Z-Image Turbo, Krea 2 Turbo, Krea 2 Identity Edit, Chroma v.46 Flash / v.48 Detail / Chroma1-HD, Qwen image-edit models, GPT Image 2, plus community fine-tunes such as Dark Beast Z-Image Turbo v9, Dark Beast KREA 2, Dark Beast Krea 2 Identity Edit, and One Obsession v22), video generation (WAN 2.2, LTX-2.3, Seedance 2.0, HappyHorse 1.1, MiniMax H3, and MiniMax H3 Turbo), audio generation (ACE-Step 1.5), LLM chat with tool calling, hosted creative tools, durable creative workflows, replay records, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`). The model catalog is discovered dynamically at runtime (`sogni.projects.getAvailableModels()`); model ids listed here are illustrative.
+This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, Z-Image / Z-Image Turbo, Krea 2 Turbo, Krea 2 Identity Edit, Chroma v.46 Flash / v.48 Detail / Chroma1-HD, Qwen image-edit models, GPT Image 2, plus community fine-tunes such as Dark Beast Z-Image Turbo v9, Dark Beast KREA 2, Dark Beast Krea 2 Identity Edit, and One Obsession v22), video generation (WAN 2.2, Wan 3, LTX-2.3, Seedance 2.0, HappyHorse 1.1, MiniMax H3, and MiniMax H3 Turbo), audio generation (ACE-Step 1.5), LLM chat with tool calling, hosted creative tools, durable creative workflows, replay records, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`). The model catalog is discovered dynamically at runtime (`sogni.projects.getAvailableModels()`); model ids listed here are illustrative.
 
 Choosing an image-edit model: pick by what the edit has to preserve, not by step count or quality tier. When a person or character must stay recognisable through the edit — style transfer, makeover, clothing or person swap, face swap, new pose or expression, character sheet — use Krea 2 Identity Edit (`krea2_identity_edit_v1_2`, or `dark_beast_krea2_identity_edit_v1_2` uncensored) with 1-2 context images. For general-purpose editing — photo transforms, in-image text, multi-person changes, combining up to 3 references — use a Qwen image-edit model. A higher-step general-purpose editor does not beat the identity model at a likeness task; it reinterprets the subject instead of preserving it. See `llms.txt` for parameters.
 
@@ -225,12 +225,13 @@ The SDK supports two families of video models with **fundamentally different FPS
 - **Frame calculation**: `duration * 16 + 1` (always uses 16, ignores fps)
 - Example: 5 seconds at 32fps = 81 frames generated → interpolated to 161 output frames
 
-### External-API Partner Models (Seedance 2.0, Happy Horse 1.1)
+### External-API Partner Models (Seedance, Happy Horse, Wan 3)
 
-**Seedance 2.0** (`seedance-2-0` / `-mini` / `-fast`) and **Happy Horse 1.1** (`happyhorse-1.1-t2v` / `-i2v` / `-r2v`) run on partner external APIs, not Sogni GPU workers:
-- **Spark-only** billing, **fixed 24fps**, and **native audio** (no separate audio params to set).
+**Seedance 2.0**, **Happy Horse 1.1**, and **Wan 3** (`wan3.0-video`) run on partner external APIs, not Sogni GPU workers:
+- **Premium Spark-only** billing and provider-owned fixed frame rates: Seedance/Happy Horse use 24fps, while Wan 3 uses 30fps. All can produce native audio; Wan 3 also supports silent output.
 - No local diffusion steps — progress is provider/ETA-derived (still a finite 0-100). Results can arrive as direct hosted URLs, preserved on `job.resultUrl` / `job.getResultUrl()`.
 - **Seedance** accepts image + video + audio references (up to 9 / 3 / 3, 12 total) via `referenceImage*` / `referenceImageUrls` / `referenceVideoUrls` / `referenceAudioUrls`. **Happy Horse** accepts **image-only** references (r2v takes 1-9 images via `referenceImage` / `referenceImageUrls`).
+- **Wan 3** is one fixed-30fps model for 2-30s T2V/I2V/FLF/R2V/A2V/V2V. It accepts up to 10 loose images, 5 videos, and 5 audios, but native frame mode cannot mix with loose references.
 - Family predicates: `isSeedanceModel()`, `isHappyhorseModel()`, `isExternalApiVideoModel()` in `src/Projects/utils/index.ts`.
 
 ### Key Files

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [5.21.0](https://github.com/Sogni-AI/sogni-client/compare/v5.20.0...v5.21.0) (2026-08-26)
+
+
+### Features
+
+* **video:** quote H3 reference input ([e720d54](https://github.com/Sogni-AI/sogni-client/commit/e720d540d693b21e97d07960f4a258ffa3872ca7))
+
+# [5.20.0](https://github.com/Sogni-AI/sogni-client/compare/v5.19.5...v5.20.0) (2026-08-25)
+
+
+### Bug Fixes
+
+* **deps:** consume Wan3 protocol ([33ad38b](https://github.com/Sogni-AI/sogni-client/commit/33ad38b428bf34d144c2686e4ecac18533a62b49))
+* **video:** harden Wan3 transport ([c38606b](https://github.com/Sogni-AI/sogni-client/commit/c38606bc0df3d4febd09e8f5b6f9d0141a132ef6))
+
+
+### Features
+
+* **video:** integrate Alibaba Wan 3 ([30dc496](https://github.com/Sogni-AI/sogni-client/commit/30dc496a2fdcb9529b8694b60161bd4e62b27232))
+* **video:** merge Wan3 integration ([1545413](https://github.com/Sogni-AI/sogni-client/commit/154541329bb6ec773f4f0fcc191a24fd26cbd2cc))
+
 ## [5.19.5](https://github.com/Sogni-AI/sogni-client/compare/v5.19.4...v5.19.5) (2026-08-25)
 
 

package/README.md

@@ -746,7 +746,7 @@ export interface ControlNetParams {
 }
 ```
 
-## Video Generation (WAN 2.2, LTX-2.3, Seedance 2.0 & Happy Horse 1.1)
+## Video Generation (WAN 2.2, Wan 3, LTX-2.3, Seedance & Happy Horse)
 
 The Sogni SDK supports advanced video generation workflows powered by **Wan 2.2 14B FP8** models. These models are available on the `fast` network and support various video generation workflows.
 
@@ -794,6 +794,7 @@ Example model IDs:
 - `happyhorse-1.1-t2v` (Happy Horse 1.1 Text-to-Video, external API, image-only references)
 - `happyhorse-1.1-i2v` (Happy Horse 1.1 Image-to-Video, external API, one first-frame image)
 - `happyhorse-1.1-r2v` (Happy Horse 1.1 Reference-to-Video, external API, 1-9 reference images)
+- `wan3.0-video` (Wan 3 unified multimodal video, external API, 2-30s, 480P/720P/1080P, fixed 30fps)
 
 The repository does not bundle sample prompts or input media for the 10Eros model. Creators
 who choose to use it must provide their own prompt and image to
@@ -804,8 +805,8 @@ who choose to use it must provide their own prompt and image to
 
 When creating video projects, you can specify:
 
-- `duration` - Duration in seconds. WAN supports 1-10s, LTX 2.5 supports 2-20s, LTX 2.3 supports 4-20s, Seedance 2.0 supports 4-15s, and Seedance 2.5 supports 4-30s.
-- `fps` - Frames per second. WAN supports 16/32 output, LTX 2.x supports 1-60 native FPS, Seedance is fixed at 24fps.
+- `duration` - Duration in seconds. WAN 2.2 supports 1-10s, Wan 3 supports 2-30s, LTX 2.5 supports 2-20s, LTX 2.3 supports 4-20s, Seedance 2.0 supports 4-15s, and Seedance 2.5 supports 4-30s.
+- `fps` - Frames per second. WAN 2.2 supports 16/32 output, Wan 3 is fixed at 30fps, LTX 2.x supports 1-60 native FPS, and Seedance is fixed at 24fps.
 - `frames` - Number of frames. Prefer `duration`; the SDK calculates model-correct frame counts.
 - `width` - Video width in pixels
 - `height` - Video height in pixels
@@ -813,18 +814,22 @@ When creating video projects, you can specify:
 - `seed` - Random seed for reproducibility
 - `referenceImage` - Reference image for workflows that require it (i2v, s2v, animate-move, animate-replace)
 - `referenceVideo` - Reference video for animate and v2v workflows
+- `referenceVideoDurations` - Required MiniMax H3 r2v durations in `[referenceVideo, ...referenceVideos]` order for the preflight quote and submitted job pricing
 - `referenceAudio` - Reference audio for sound-to-video workflow
-- `referenceImageUrls` - Loose image context URLs for Seedance and Happy Horse (Happy Horse r2v takes 1-9 reference images here); Seedance 2.0 accepts 9 image assets and Seedance 2.5 accepts 30
-- `referenceVideoUrls` - Seedance-only video context URLs; Seedance 2.0 accepts 3 video assets and Seedance 2.5 accepts 10
-- `referenceAudioUrls` - Seedance-only audio context URLs; Seedance 2.0 accepts 3 audio assets and Seedance 2.5 accepts 10
+- `referenceImageUrls` - Loose image context URLs for Seedance, Happy Horse, and Wan 3; Wan 3 accepts up to 10
+- `referenceVideoUrls` - Loose video context URLs for Seedance and Wan 3; Wan 3 accepts up to 5
+- `referenceAudioUrls` - Loose audio context URLs for Seedance and Wan 3; Wan 3 accepts up to 5
 - `seedanceTaskType` - Seedance 2.5 loose-reference operation: `reference`, `edit`, or `extend`. Edit and extend require a reference video.
 - `hasVideoInput` - Estimate-only flag for `estimateVideoCost`; set this when estimating a canonical Seedance video-input job without passing `referenceVideo`/`referenceVideoUrls`
 - `referenceImageCount` - Optional estimate-only count of image references the video job will submit; models whose pricing does not use it ignore it
+- `referenceVideoCount` / `referenceVideoDurationSeconds` - Estimate-only MiniMax H3 r2v input metadata; reference-video seconds use the full resolution-tier input rate ($0.05/s at 480p or $0.08/s at 544/768p), even with Turbo output
 
 Seedance 2.0 can combine image, video, and audio reference assets in one external API request. Reference limits are up to 9 image assets, 3 video assets, 3 audio assets, and 12 asset files total. Text+audio without at least one image or video reference is not supported by Seedance. URL-array references must be HTTPS URLs that the vendor can fetch; local multi-reference files should be uploaded first, as shown in `examples/workflow_partner_seedance_video.mjs`. In prompts and creative briefs, refer to attachments by Seedance-style tags: `@Image1`, `@Video1`, and `@Audio1`, counted independently by modality in attachment order. Assign each useful reference a role, such as product identity, motion timing, camera path, edit rhythm, background music, or speech reference. Prefer positive preservation language like "maintain the same product silhouette and logo placement from @Image1"; exact readable text, logos, lip-sync, voice cloning, and real-human-reference behavior still need review. Seedance dispatch omits negative prompts; Wan 2.2 and LTX 2.3 video models can still use `negativePrompt`. Seedance jobs are Spark-only and should not use SOGNI token fallback.
 
 Seedance 2.5 raises the reference limits to 30 images, 10 videos, 10 audios, and 50 total files, and it permits audio-only loose-reference generation. Its frame-conditioned, edit, and extend operations inherit source aspect ratio. Send `seedanceTaskType: 'edit'` for source-video edits and `seedanceTaskType: 'extend'` for continuation; the Sogni vendor adapter applies Seedance 2.5's required adaptive ratio and provider-selected edit duration. Use `reference` when media supplies creative guidance for a newly generated video. Loose-reference requests require an explicit task type.
 
+Wan 3 uses the single exact model ID `wan3.0-video` for text, first-frame, first+last-frame, loose-reference, audio-driven, and video-edit/extend workflows. It accepts fixed or smart 2-30 second output at 480P/720P/1080P and fixed 30fps, with `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16` ratio. Native audio defaults on; provider prompt expansion and watermarking are independently controllable. It accepts up to 10 loose images, 5 videos, and 5 audios, plus either one public document or one webpage. Native first/last frames cannot be mixed with loose media or document/web context. In English prompts, identify loose assets as `Image 1`, `Video 1`, and `Audio 1`, numbered independently by type. Extension requires `ratio: 'adaptive'` and an explicit continuation prompt. Wan 3 has no `negativePrompt` request field and is Premium Spark-only.
+
 ### Text-to-Video Example
 
 ```javascript