Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

seedance.ts

324 lines10.4 KB

1import type {
2 BytePlusVideoModel,
3 BytePlusVideoModelOrString,
4 BytePlusVideoRatio,
5 BytePlusVideoResolution,
6 BytePlusVideoServiceTier,
7} from '@tanstack/ai-byteplus'
8​
9/**
10 * Seedance Studio catalog — the client half of the per-model capability
11 * surface.
12 *
13 * Everything the adapter can tell us at runtime (duration range, resolution
14 * tiers, first/last-frame support, reference-media support) is read from
15 * `@tanstack/ai-byteplus` on the server and shipped down as
16 * {@link SeedanceCapability}; this file only carries what the package
17 * documents in prose rather than in a runtime table: display copy, and the
18 * per-field applicability policy for the provider options.
19 */
20​
21/** Which optional provider-option fields a model accepts. */
22export interface SeedanceExtras {
23 /**
24 * `generate_audio` — accepted by every model at the validation layer, but
25 * only Seedance 2.5, the 2.0 family and 1.5-pro actually produce an audio
26 * track.
27 */
28 generateAudio: boolean
29 /** `camera_fixed` — Seedance 1.x only; the 2.x family rejects it. */
30 cameraFixed: boolean
31 /** `service_tier: 'flex'` — Seedance 1.x only (no offline tier on 2.x). */
32 serviceTier: boolean
33 /** `frames` — Seedance 1.0-pro and 1.0-pro-fast only. */
34 frames: boolean
35 /** `draft` — Seedance 1.5-pro only. */
36 draft: boolean
37 /** `priority` (0-9) — Seedance 2.5 and the 2.0 family. */
38 priority: boolean
39 /** `duration: -1` (model picks the length) — Seedance 2.5, 2.0 and 1.5-pro. */
40 autoDuration: boolean
42​
43export interface SeedanceModelEntry {
44 id: BytePlusVideoModelOrString
45 name: string
46 blurb: string
47 extras: SeedanceExtras
49​
50/** Resolves only for `never`; anything else is a compile error naming it. */
51type AssertNever<T extends never> = T
52​
53/**
54 * The Seedance models, with option applicability from
55 * `BytePlusVideoProviderOptions` (2.0/1.x live-probed; 2.5 from ModelArk
56 * docs). Ark 400s on an inapplicable field rather than ignoring it, so these
57 * flags decide what the studio is allowed to send — not just what it renders.
58 */
59export const SEEDANCE_MODELS = [
60 {
61 id: 'dreamina-seedance-2-5-260628',
62 name: 'Seedance 2.5',
63 blurb: 'Current multimodal flagship — up to 30s, audio-only references',
64 extras: {
65 generateAudio: true,
66 cameraFixed: false,
67 serviceTier: false,
68 frames: false,
69 draft: false,
70 priority: true,
71 autoDuration: true,
72 },
73 },
74 {
75 id: 'dreamina-seedance-2-0-260128',
76 name: 'Seedance 2.0',
77 blurb: '2.0 flagship — the only Seedance model with a 4k tier',
78 extras: {
79 generateAudio: true,
80 cameraFixed: false,
81 serviceTier: false,
82 frames: false,
83 draft: false,
84 priority: true,
85 autoDuration: true,
86 },
87 },
88 {
89 id: 'dreamina-seedance-2-0-fast-260128',
90 name: 'Seedance 2.0 Fast',
91 blurb: 'Faster 2.0 sibling, capped at 720p',
92 extras: {
93 generateAudio: true,
94 cameraFixed: false,
95 serviceTier: false,
96 frames: false,
97 draft: false,
98 priority: true,
99 autoDuration: true,
100 },
101 },
102 {
103 id: 'dreamina-seedance-2-0-mini-260615',
104 name: 'Seedance 2.0 Mini',
105 blurb: 'Smallest 2.0 model, still takes reference media',
106 extras: {
107 generateAudio: true,
108 cameraFixed: false,
109 serviceTier: false,
110 frames: false,
111 draft: false,
112 priority: true,
113 autoDuration: true,
114 },
115 },
116 {
117 id: 'seedance-1-5-pro-251215',
118 name: 'Seedance 1.5 Pro',
119 blurb: 'Audio-capable 1.x flagship with cheap draft renders',
120 extras: {
121 generateAudio: true,
122 cameraFixed: true,
123 serviceTier: true,
124 frames: false,
125 draft: true,
126 priority: false,
127 autoDuration: true,
128 },
129 },
130 {
131 id: 'seedance-1-0-pro-250528',
132 name: 'Seedance 1.0 Pro',
133 blurb: 'Frame-count output and first-and-last-frame mode',
134 extras: {
135 generateAudio: false,
136 cameraFixed: true,
137 serviceTier: true,
138 frames: true,
139 draft: false,
140 priority: false,
141 autoDuration: false,
142 },
143 },
144 {
145 id: 'seedance-1-0-pro-fast-251015',
146 name: 'Seedance 1.0 Pro Fast',
147 blurb: 'Cheapest run — text-to-video and opening-frame only',
148 extras: {
149 generateAudio: false,
150 cameraFixed: true,
151 serviceTier: true,
152 frames: true,
153 draft: false,
154 priority: false,
155 autoDuration: false,
156 },
157 },
158] as const satisfies ReadonlyArray<SeedanceModelEntry>
159​
160/**
161 * Compile-time link between this catalog and the package's model list: a new
162 * model shipping in `@tanstack/ai-byteplus` fails the example's build here —
163 * naming the id it is missing — instead of silently going absent from the
164 * picker with no capability copy or option policy.
165 */
166export type SeedanceCatalogCoversEveryModel = AssertNever<
167 Exclude<BytePlusVideoModel, (typeof SEEDANCE_MODELS)[number]['id']>
169​
170/**
171 * Look up a catalog entry, or `undefined` for an id this file has no policy
172 * for. There is deliberately no fallback entry: handing back some other
173 * model's option policy would gate the studio on the wrong model's rules —
174 * exactly the class of bug the per-model gating exists to prevent. A custom
175 * id goes through the explicit unknown-model path instead.
176 */
177export function seedanceModel(
178 id: BytePlusVideoModel,
179): SeedanceModelEntry | undefined {
180 return SEEDANCE_MODELS.find((entry) => entry.id === id)
182​
183/**
184 * The runtime half of a model's capabilities, derived on the server from the
185 * adapter's own metadata rather than restated here.
186 */
187export interface SeedanceCapability {
188 model: BytePlusVideoModel
189 /** Tiers this model accepts, in ascending order. */
190 resolutions: Array<BytePlusVideoResolution>
191 /** Whole-second range from the adapter's `availableDurations()`. */
192 duration: { min: number; max: number; step: number }
193 /** Whether an `end_frame` image is accepted (`flf2v`). */
194 supportsLastFrame: boolean
195 /** Whether reference images / video / audio are accepted (`r2v`). */
196 supportsReferenceMedia: boolean
198​
199/**
200 * Placeholder for the advanced custom-id field when trying an id this package
201 * has not catalogued yet. Known models (including Seedance 2.5) live in the
202 * picker above.
203 */
204export const SEEDANCE_CUSTOM_MODEL_PLACEHOLDER = 'dreamina-seedance-…-yymmdd'
205​
206/**
207 * Option applicability for an id the package has no table for: everything on.
208 *
209 * This is not optimism. `@tanstack/ai-byteplus` deliberately leaves an unknown
210 * id ungated — the adapter's per-model guards switch off and Ark judges the
211 * request — because clamping a future model against today's tables would
212 * reject requests the API would have accepted. The studio mirrors that: it
213 * offers the full surface and lets the API be the authority.
214 */
215export const SEEDANCE_UNKNOWN_MODEL_EXTRAS: SeedanceExtras = {
216 generateAudio: true,
217 cameraFixed: true,
218 serviceTier: true,
219 frames: true,
220 draft: true,
221 priority: true,
222 autoDuration: true,
224​
225/**
226 * Every resolution tier Seedance has shipped so far. Which of them a known
227 * model accepts is decided by the adapter (see `SeedanceCapability`); for an
228 * unknown model these are offered as a starting point alongside a free-text
229 * field, since a future model may bring a tier that does not exist today.
230 */
231export const SEEDANCE_RESOLUTION_TIERS: ReadonlyArray<BytePlusVideoResolution> =
232 ['480p', '720p', '1080p', '4k']
233​
234/**
235 * The studio's curated slice of `BytePlusVideoProviderOptions`, as sent from
236 * the browser. The server maps it onto the provider's own (snake_case) field
237 * names and drops anything the selected model does not accept.
238 */
239export interface SeedanceJobOptions {
240 ratio?: BytePlusVideoRatio
241 resolution?: BytePlusVideoResolution
242 /**
243 * Full `ratio_resolution` template, used instead of `ratio`/`resolution` for
244 * a custom model id. Those two are typed against the tiers this package
245 * knows; the generic `size` is the open path, and the adapter only checks an
246 * unknown model's template shape before handing the values to Ark.
247 */
248 size?: string
249 /** Whole seconds, or `-1` to let the model choose (2.5 / 2.0 / 1.5-pro). */
250 duration?: number
251 /** Frame count instead of seconds; wins over `duration` server-side. */
252 frames?: number
253 /** `[-1, 2^32-1]`; `-1` leaves generation unseeded. */
254 seed?: number
255 watermark?: boolean
256 generateAudio?: boolean
257 cameraFixed?: boolean
258 serviceTier?: BytePlusVideoServiceTier
259 draft?: boolean
260 /** Queue priority `[0, 9]`. */
261 priority?: number
263​
264/**
265 * How the prompt's media parts are shaped. Seedance sorts them into mutually
266 * exclusive task types, so the studio picks one mode rather than letting a
267 * user mix frame roles with reference roles into a request the adapter would
268 * reject.
269 */
270export type SeedanceInputMode =
271 | 'text'
272 | 'first-frame'
273 | 'first-last-frame'
274 | 'reference'
275​
276/**
277 * Aspect ratios the create endpoint accepts. `adaptive` (follow the input
278 * frame) only makes sense with an image attached — Seedance 1.0 rejects it
279 * outright for text-to-video — so the studio offers it conditionally.
280 */
281export const SEEDANCE_RATIOS: ReadonlyArray<BytePlusVideoRatio> = [
282 '16:9',
283 '9:16',
284 '4:3',
285 '3:4',
286 '1:1',
287 '21:9',
289​
290/** Seedance renders at 24 fps, which is what makes `frames` a duration. */
291export const SEEDANCE_FPS = 24
292​
293/**
294 * Snap a frame count onto the grid Seedance accepts: the integers of the form
295 * `25 + 4n` inside `[29, 289]`.
296 */
297export function snapSeedanceFrames(frames: number): number {
298 const steps = Math.min(66, Math.max(1, Math.round((frames - 25) / 4)))
299 return 25 + steps * 4
301​
302/** Smallest / largest frame counts on that grid. */
303export const SEEDANCE_MIN_FRAMES = snapSeedanceFrames(0)
304export const SEEDANCE_MAX_FRAMES = snapSeedanceFrames(Number.MAX_SAFE_INTEGER)
305​
306/** One-line capability summary shown under each model in the picker. */
307export function describeSeedanceModel(
308 entry: SeedanceModelEntry,
309 capability: SeedanceCapability | undefined,
310): string {
311 if (!capability) return entry.blurb
312 const parts = [
313 `${capability.duration.min}-${capability.duration.max}s`,
314 capability.resolutions.join(' / '),
315 ]
316 if (entry.extras.generateAudio) parts.push('audio')
317 if (capability.supportsReferenceMedia) parts.push('references')
318 if (capability.supportsLastFrame) parts.push('first+last frame')
319 if (entry.extras.serviceTier) parts.push('flex tier')
320 if (entry.extras.frames) parts.push('frame count')
321 if (entry.extras.draft) parts.push('draft')
322 if (entry.extras.priority) parts.push('priority')
323 return parts.join(' · ')