Merge branch 'main' into worktree-resilient-popping-knuth

Author: AlemTuzlak

.changeset/seedance-2-5.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/ai-byteplus': patch
+---
+
+Add first-class Seedance 2.5 support (`dreamina-seedance-2-5-260628`).
+
+The model is fully open on ModelArk with documented capabilities: 4–30s
+duration (or `-1`), 480p/720p only, multimodal reference media including
+audio-only input, first-and-last-frame mode, `priority`, `generate_audio`, and
+`output_format` (`mp4` | `mov`). The video adapter, typed model tables, unit
+tests, docs, and Seedance Studio example catalog all treat it as a known
+model rather than an escape-hatch string.

docs/adapters/byteplus.md

@@ -321,42 +321,52 @@ Seedance options are model-specific, and **Ark rejects an inapplicable field wit
 
 | Option | Models that accept it |
 | --- | --- |
-| `service_tier` (`'default'` \| `'flex'`) | Seedance 1.x only — the 2.0 family rejects it |
+| `service_tier` (`'default'` \| `'flex'`) | Seedance 1.x only — Seedance 2.5 and the 2.0 family reject it |
 | `camera_fixed` | Seedance 1.x only |
 | `frames` (fractional-second output, `25 + 4n` in `[29, 289]`) | `seedance-1-0-pro-250528`, `seedance-1-0-pro-fast-251015` |
 | `draft` (cheap low-fidelity preview) | `seedance-1-5-pro-251215` only |
-| `priority` (`0`–`9`) | the `dreamina-seedance-2-0-*` family only |
-| `duration: -1` (model picks the length) | Seedance 2.0 and `seedance-1-5-pro-251215` |
+| `priority` (`0`–`9`) | Seedance 2.5 and the `dreamina-seedance-2-0-*` family |
+| `duration: -1` (model picks the length) | Seedance 2.5, 2.0 and `seedance-1-5-pro-251215` |
+| `output_format` (`'mp4'` \| `'mov'`) | Seedance 2.5 (default `mp4`) |
 | `seed`, `watermark`, `generate_audio`, `return_last_frame`, `callback_url` | every model |
 
-`watermark` defaults to `false` for video (the opposite of Seedream images). `generate_audio` is accepted everywhere but only Seedance 2.0 and 1.5-pro actually produce an audio track.
+`watermark` defaults to `false` for video (the opposite of Seedream images). `generate_audio` is accepted everywhere but only Seedance 2.5, 2.0 and 1.5-pro actually produce an audio track.
 
-Resolutions are per model too, and the shipped table comes from live probes rather than the published docs: there is **no 2K tier on any Seedance model**, `4k` exists only on `dreamina-seedance-2-0-260128`, and `seedance-1-0-pro-fast-251015` does accept `1080p` despite being documented as 480p/720p only. An unsupported combination is caught locally with a clear error before the request goes out.
+Resolutions are per model too: there is **no 2K tier on any Seedance model**, `4k` exists only on `dreamina-seedance-2-0-260128`, Seedance 2.5 is **480p/720p only**, and `seedance-1-0-pro-fast-251015` does accept `1080p` despite older prose listing it as 480p/720p only. An unsupported combination is caught locally with a clear error before the request goes out.
 
-Reference media follows the shared [role hints](../media/video-generation#role-hints) — `start_frame`, `end_frame` and `reference`. The Seedance 2.0 family takes full multimodal references (reference images, video and audio); the 1.x models take start/end frames only, and `seedance-1-0-pro-fast-251015` takes a start frame only.
+Reference media follows the shared [role hints](../media/video-generation#role-hints) — `start_frame`, `end_frame` and `reference`. Seedance 2.5 and the 2.0 family take full multimodal references (reference images, video and audio); Seedance 2.5 additionally accepts **audio-only** reference input and up to 30 reference images / 10 videos / 10 audio clips (2.0 is 9 / 3 / 3). The 1.x models take start/end frames only, and `seedance-1-0-pro-fast-251015` takes a start frame only.
 
 ### Seedance 2.5
 
-Seedance 2.5 was announced on 2026-07-31, initially on BytePlus's consumer surfaces. Its Ark id — `dreamina-seedance-2-5-260628` — is real and reachable, but it is **activation-gated per account**: until the model is switched on in the Ark Console, Ark answers `404 ModelNotOpen`.
-
-Because its capabilities could not be probed from a non-activated account, 2.5 is **deliberately absent from the typed model tables** above. It is still usable today — `byteplusVideo()`'s model parameter accepts any string, so an id BytePlus publishes after this release works without upgrading the package:
+Seedance 2.5 (`dreamina-seedance-2-5-260628`) is a first-class model in this package. It is the current multimodal flagship for longer clips (up to **30 seconds**), audio-only reference input, and `output_format: 'mov'`. Like the 2.0 series it may still require model activation / a resource pack in the Ark Console before the account can call it (`404 ModelNotOpen` until then).
 
 ```typescript
 import { generateVideo } from '@tanstack/ai'
 import { byteplusVideo } from '@tanstack/ai-byteplus'
 
-// Activate Seedance 2.5 in the Ark Console first, or this 404s.
 const { jobId } = await generateVideo({
   adapter: byteplusVideo('dreamina-seedance-2-5-260628'),
   prompt: 'a guitar being played in a store',
   size: '16:9_720p',
-  duration: 5,
+  duration: 10,
+  modelOptions: {
+    generate_audio: true,
+    priority: 5,
+    output_format: 'mp4',
+  },
 })
 ```
 
-An unknown id relaxes both halves of the adapter: `size` widens to any string, provider options are ungated, and the local runtime guards that encode per-model capabilities — resolution tiers, closing-frame and reference-media support, frame cardinality and mode exclusivity, duration snapping — stand down so Ark validates the request instead. Known ids keep their probe-verified narrowing. Typed narrowing for 2.5 follows in a package update once its capabilities can be verified.
+| Capability | Seedance 2.5 |
+| --- | --- |
+| Duration | 4–30s, or `-1` (model chooses; required for video-editing tasks) |
+| Resolution | `480p`, `720p` (default `720p`) — no 1080p / 4k |
+| Reference media | images 1–30, videos 0–10, audio 0–10; **audio-only allowed** |
+| First + last frame | yes |
+| `priority` / `generate_audio` | yes |
+| `service_tier` / `camera_fixed` / `frames` / `draft` | no |
 
-The quickest way to try a newly-released id is the [Seedance Studio example](https://github.com/TanStack/ai/tree/main/examples/ts-react-media): its **Advanced: custom model id** field (placeholder `dreamina-seedance-2-5-260628`) takes an arbitrary id, switches the studio into unknown-model mode with every option enabled, and spells the activation caveat out in the UI — so a `ModelNotOpen` response reads as expected rather than broken.
+`byteplusVideo()` still accepts any string for ids BytePlus ships between package releases. An unknown id relaxes local guards so Ark validates the request; known ids (including 2.5) keep their documented narrowing.
 
 ### Seedance here vs. Seedance via fal
 
@@ -495,7 +505,7 @@ Audio can be a `File`, base64, a data URL or a public URL, up to two hours and 1
 ## Supported models
 
 - **Chat** — `dola-seed-2-1-turbo-260628`, `seed-2-0-lite-260428`, `seed-2-0-mini-260428`, `seed-2-0-pro-260328`, `seed-2-0-lite-260228`, `seed-2-0-mini-260215`, `seed-2-0-code-preview-260328`, `seed-1-8-251228`, `seed-1-6-250915`, `seed-1-6-250615`, `seed-1-6-flash-250715`, `seed-1-6-flash-250615`, `glm-5-2-260617`, `glm-4-7-251222`, `deepseek-v4-pro-260425`, `deepseek-v4-flash-260425`, `deepseek-v3-2-251201`, `gpt-oss-120b-250805`.
-- **Video** — `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`, `dreamina-seedance-2-0-mini-260615`, `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`, `seedance-1-0-pro-fast-251015`. (Seedance 2.5, `dreamina-seedance-2-5-260628`, is untyped-but-usable pending account activation — see [Seedance 2.5](#seedance-25).)
+- **Video** — `dreamina-seedance-2-5-260628`, `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`, `dreamina-seedance-2-0-mini-260615`, `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`, `seedance-1-0-pro-fast-251015`.
 - **Image** — `dola-seedream-5-0-pro-260628`, `seedream-5-0-260128`, `seedream-5-0-lite-260128`, `seedream-4-5-251128`, `seedream-4-0-250828`.
 - **Speech** — `seed-audio-1.0` (TTS) and `seed-asr` (transcription).
 

docs/config.json

@@ -442,7 +442,7 @@
           "label": "Video Generation",
           "to": "media/video-generation",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-04"
+          "updatedAt": "2026-08-07"
         },
         {
           "label": "Generation Hooks",
@@ -869,7 +869,8 @@
         {
           "label": "BytePlus",
           "to": "adapters/byteplus",
-          "addedAt": "2026-08-04"
+          "addedAt": "2026-08-04",
+          "updatedAt": "2026-08-07"
         }
       ]
     },

docs/media/video-generation.md

@@ -392,7 +392,7 @@ await generateVideo({
 | **OpenAI**   | Sora-2 / Sora-2-Pro → the image part goes to `input_reference`; flattened text is the prompt. Single image only — throws if more than one. |
 | **fal.ai**   | Field names resolve per endpoint from a map generated from the fal SDK's endpoint types — e.g. `role: 'start_frame'` lands on `image_url` for Kling/Veo image-to-video, `first_frame_url` for first-last-frame endpoints, and `start_image_url` otherwise. Defaults: single input → `image_url` (start frame); `role: 'end_frame'` → `end_image_url`; `role: 'reference'` / `'character'` → `reference_image_urls`. Override per-endpoint via `modelOptions` — the media-conditioning fields are typed optional there (even when the endpoint requires them) since they usually arrive as prompt parts. |
 | **Gemini**   | Veo → the first un-roled / `'start_frame'` image becomes the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages` (asset references, Veo 3.1). Throws on multiple starting images. |
-| **BytePlus** | Seedance → a single un-roled or `'start_frame'` image becomes `first_frame`; `'end_frame'` → `last_frame` (needs a first frame alongside it, and is rejected by `seedance-1-0-pro-fast-251015`); `'reference'` / `'character'` → `reference_image`, video parts → `reference_video`, audio parts → `reference_audio` (Seedance 2.0 family only). Frame roles and reference roles are mutually exclusive modes — mixing them throws. |
+| **BytePlus** | Seedance → a single un-roled or `'start_frame'` image becomes `first_frame`; `'end_frame'` → `last_frame` (needs a first frame alongside it, and is rejected by `seedance-1-0-pro-fast-251015`); `'reference'` / `'character'` → `reference_image`, video parts → `reference_video`, audio parts → `reference_audio` (Seedance 2.5 and 2.0 family; 2.5 also accepts audio-only reference input). Frame roles and reference roles are mutually exclusive modes — mixing them throws. |
 
 Adapters whose underlying API can't accept image inputs throw a clear
 runtime error so calls fail fast.
@@ -739,7 +739,7 @@ Generated clips include an audio track. When the job completes, the adapter repo
 
 #### BytePlus (Seedance) Model Options
 
-Seedance is aspect-ratio sized like Grok Imagine — `size` takes a `ratio` or `ratio_resolution` template. Ratios are `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, `21:9` and `adaptive`; resolutions are `480p`, `720p`, `1080p` and (on `dreamina-seedance-2-0-260128` only) `4k`. There is no 2K tier on any Seedance model:
+Seedance is aspect-ratio sized like Grok Imagine — `size` takes a `ratio` or `ratio_resolution` template. Ratios are `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, `21:9` and `adaptive`; resolutions are `480p`, `720p`, `1080p` and (on `dreamina-seedance-2-0-260128` only) `4k`. Seedance 2.5 (`dreamina-seedance-2-5-260628`) is 480p/720p only and runs up to 30 seconds. There is no 2K tier on any Seedance model:
 
 ```typescript
 import { generateVideo } from '@tanstack/ai'
@@ -753,12 +753,12 @@ const { jobId } = await generateVideo({
   modelOptions: {
     seed: 42,
     generate_audio: true,
-    priority: 5, // Seedance 2.0 family only — queue priority, 0-9
+    priority: 5, // Seedance 2.5 / 2.0 family — queue priority, 0-9
   },
 })
 ```
 
-Options are **model-specific and validated server-side**: Ark rejects an inapplicable field with a `400` instead of ignoring it. `service_tier` and `camera_fixed` are Seedance 1.x only, `frames` works on the 1.0-pro models, `draft` on 1.5-pro, `priority` on the 2.0 family, and `duration: -1` (let the model choose) on 2.0 and 1.5-pro. Durations are 4–15s on the 2.0 family, 4–12s on 1.5-pro and 2–12s on the 1.0-pro models.
+Options are **model-specific and validated server-side**: Ark rejects an inapplicable field with a `400` instead of ignoring it. `service_tier` and `camera_fixed` are Seedance 1.x only, `frames` works on the 1.0-pro models, `draft` on 1.5-pro, `priority` on Seedance 2.5 and the 2.0 family, and `duration: -1` (let the model choose) on 2.5, 2.0 and 1.5-pro. Durations are 4–30s on Seedance 2.5, 4–15s on the 2.0 family, 4–12s on 1.5-pro and 2–12s on the 1.0-pro models.
 
 **Seedance video URLs expire 24 hours after the task completes** (the task record is kept for seven days), so persist the bytes rather than the link. See the [BytePlus adapter](../adapters/byteplus#video-generation-seedance) for the full option table.
 

examples/ts-react-media/src/components/SeedanceStudio.tsx

@@ -870,9 +870,8 @@ export default function SeedanceStudio({
                   <p className="text-xs text-amber-200/90">
                     Capabilities unverified — every option below is enabled and
                     the API validates the request, because the adapter switches
-                    its per-model guards off for an id it has no table for.
-                    Seedance 2.5 additionally requires activation in the Ark
-                    Console; without it the task returns 404{' '}
+                    its per-model guards off for an id it has no table for. A
+                    model that is not activated on your Ark account returns 404{' '}
                     <code className="text-amber-300">ModelNotOpen</code>.
                   </p>
                 </div>
@@ -1110,7 +1109,7 @@ export default function SeedanceStudio({
         </div>
 
         {entry.extras.priority && (
-          <Control label="Queue priority" hint="0-9, Seedance 2.0 family only">
+          <Control label="Queue priority" hint="0-9, Seedance 2.5 / 2.0 family">
             <div className="flex items-center gap-3">
               <input
                 type="range"

examples/ts-react-media/src/lib/seedance.ts

@@ -22,20 +22,21 @@ import type {
 export interface SeedanceExtras {
   /**
    * `generate_audio` — accepted by every model at the validation layer, but
-   * only the Seedance 2.0 family and 1.5-pro actually produce an audio track.
+   * only Seedance 2.5, the 2.0 family and 1.5-pro actually produce an audio
+   * track.
    */
   generateAudio: boolean
-  /** `camera_fixed` — Seedance 1.x only; the 2.0 family rejects it. */
+  /** `camera_fixed` — Seedance 1.x only; the 2.x family rejects it. */
   cameraFixed: boolean
-  /** `service_tier: 'flex'` — Seedance 1.x only (no offline tier on 2.0). */
+  /** `service_tier: 'flex'` — Seedance 1.x only (no offline tier on 2.x). */
   serviceTier: boolean
   /** `frames` — Seedance 1.0-pro and 1.0-pro-fast only. */
   frames: boolean
   /** `draft` — Seedance 1.5-pro only. */
   draft: boolean
-  /** `priority` (0-9) — Seedance 2.0 family only. */
+  /** `priority` (0-9) — Seedance 2.5 and the 2.0 family. */
   priority: boolean
-  /** `duration: -1` (model picks the length) — Seedance 2.0 and 1.5-pro. */
+  /** `duration: -1` (model picks the length) — Seedance 2.5, 2.0 and 1.5-pro. */
   autoDuration: boolean
 }
 
@@ -50,16 +51,30 @@ export interface SeedanceModelEntry {
 type AssertNever<T extends never> = T
 
 /**
- * The six Seedance models, with the option applicability probed live against
- * Ark on 2026-07-31 and documented on `BytePlusVideoProviderOptions`. Ark 400s
- * on an inapplicable field rather than ignoring it, so these flags decide what
- * the studio is allowed to send — not just what it renders.
+ * The Seedance models, with option applicability from
+ * `BytePlusVideoProviderOptions` (2.0/1.x live-probed; 2.5 from ModelArk
+ * docs). Ark 400s on an inapplicable field rather than ignoring it, so these
+ * flags decide what the studio is allowed to send — not just what it renders.
  */
 export const SEEDANCE_MODELS = [
+  {
+    id: 'dreamina-seedance-2-5-260628',
+    name: 'Seedance 2.5',
+    blurb: 'Current multimodal flagship — up to 30s, audio-only references',
+    extras: {
+      generateAudio: true,
+      cameraFixed: false,
+      serviceTier: false,
+      frames: false,
+      draft: false,
+      priority: true,
+      autoDuration: true,
+    },
+  },
   {
     id: 'dreamina-seedance-2-0-260128',
     name: 'Seedance 2.0',
-    blurb: 'Flagship — the only Seedance model with a 4k tier',
+    blurb: '2.0 flagship — the only Seedance model with a 4k tier',
     extras: {
       generateAudio: true,
       cameraFixed: false,
@@ -143,10 +158,10 @@ export const SEEDANCE_MODELS = [
 ] as const satisfies ReadonlyArray<SeedanceModelEntry>
 
 /**
- * Compile-time link between this catalog and the package's model list: a
- * seventh model shipping in `@tanstack/ai-byteplus` fails the example's build
- * here — naming the id it is missing — instead of silently going absent from
- * the picker with no capability copy or option policy.
+ * Compile-time link between this catalog and the package's model list: a new
+ * model shipping in `@tanstack/ai-byteplus` fails the example's build here —
+ * naming the id it is missing — instead of silently going absent from the
+ * picker with no capability copy or option policy.
  */
 export type SeedanceCatalogCoversEveryModel = AssertNever<
   Exclude<BytePlusVideoModel, (typeof SEEDANCE_MODELS)[number]['id']>
@@ -182,14 +197,11 @@ export interface SeedanceCapability {
 }
 
 /**
- * Placeholder for the advanced custom-id field: the real Seedance 2.5 id.
- *
- * The June date suffix is the whole reason it needs typing out — guessing ids
- * around the 2026-07-31 announcement never landed on it. The id is reachable
- * but activation-gated: an account that has not enabled it in the Ark Console
- * gets 404 `ModelNotOpen`.
+ * Placeholder for the advanced custom-id field when trying an id this package
+ * has not catalogued yet. Known models (including Seedance 2.5) live in the
+ * picker above.
  */
-export const SEEDANCE_CUSTOM_MODEL_PLACEHOLDER = 'dreamina-seedance-2-5-260628'
+export const SEEDANCE_CUSTOM_MODEL_PLACEHOLDER = 'dreamina-seedance-…-yymmdd'
 
 /**
  * Option applicability for an id the package has no table for: everything on.
@@ -234,7 +246,7 @@ export interface SeedanceJobOptions {
    * unknown model's template shape before handing the values to Ark.
    */
   size?: string
-  /** Whole seconds, or `-1` to let the model choose (2.0 / 1.5-pro only). */
+  /** Whole seconds, or `-1` to let the model choose (2.5 / 2.0 / 1.5-pro). */
   duration?: number
   /** Frame count instead of seconds; wins over `duration` server-side. */
   frames?: number

examples/ts-react-media/src/lib/server-functions.ts

@@ -558,8 +558,7 @@ export const getSeedanceCapabilitiesFn = createServerFn({
 interface SeedanceRequest {
   prompt: MediaPrompt
   // Open by design: the studio's advanced field takes an id this package
-  // has no metadata for (Seedance 2.5 today), which the adapter forwards
-  // ungated for Ark to judge.
+  // has no metadata for, which the adapter forwards ungated for Ark to judge.
   model: BytePlusVideoModelOrString
   options?: SeedanceJobOptions
 }

packages/ai-byteplus/README.md

@@ -166,7 +166,8 @@ Result URLs expire after 24 hours; pass `response_format: 'b64_json'` in
 - **Chat** — `dola-seed-2-1-turbo-260628`, the `seed-2-0-*` family,
   `seed-1-8-251228`, the `seed-1-6-*` family, plus `glm-*`, `deepseek-*` and
   `gpt-oss-120b-250805`.
-- **Video** — `dreamina-seedance-2-0-260128` (and `-fast-`/`-mini-`),
+- **Video** — `dreamina-seedance-2-5-260628`,
+  `dreamina-seedance-2-0-260128` (and `-fast-`/`-mini-`),
   `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`,
   `seedance-1-0-pro-fast-251015`.
 - **Image** — `dola-seedream-5-0-pro-260628`, `seedream-5-0-260128`,