AI SDK ByteDance Provider 演进全解从 Seedance 视频到 Seedream 图像的版本路线图与实现剖析【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/bytedance是 AI SDKThe AI Toolkit for TypeScript中专用于字节跳动 BytePlus ModelArk 平台的 Provider 包覆盖 Seedance 视频生成与 Seedream 图像生成两大模型家族。本文以该包 CHANGELOG.md 为骨架完整梳理从 1.0.0 初始发布到 2.0.42 的版本演进主线并结合 README.md、Provider 工厂源码、视频模型实现、图像模型实现 及其测试用例展开底层原理。读完本文你将掌握如何通过generateVideo的异步轮询与 Webhook 机制消费 Seedance 模型、doStart/doStatus的异步任务协议如何工作、Seedream 图像模型的全部 Provider 参数语义以及 Provider 在 URL 安全、ESM 工程化上的关键实践。一、包定位ByteDance 在 AI SDK 生态中的角色ai-sdk/bytedance是 AI SDK 的标准 Provider 包之一核心使命是把 BytePlus ModelArk 的视频/图像生成 API 以统一、类型安全的方式接入 AI SDK 的generateVideo/generateImage调用链。从 package.json 可以看到它只依赖两个基础包ai-sdk/provider模型接口契约与ai-sdk/provider-utilsHTTP、Schema、工具函数并通过 peerDependencies 声明zod ^3.25.76 || ^4.1.8。与语言模型 Provider 不同ByteDance 包不提供 embeddingModel 与 languageModel在 bytedance-provider.ts 中这两个方法直接抛出NoSuchModelError只开放video/videoModel与image/imageModel四个工厂方法。包名关键词也印证了这一点ai、bytedance、seedance、video。从源码结构看src/下共 12 个文件包内包含三组对称设计视频侧bytedance-video-model.ts模型实现、bytedance-video-model-options.tsProvider 参数与 zod 校验、bytedance-video-settings.ts模型 ID 枚举图像侧bytedance-image-model.ts、bytedance-image-model-options.ts、bytedance-image-settings.ts公共层bytedance-provider.ts工厂、bytedance-config.ts配置契约、index.ts导出面、version.ts。当前版本对应的模型清单来自 bytedance-video-settings.ts 与 bytedance-image-settings.ts类型模型 ID视频dreamina-seedance-2-0-fast-260128、dreamina-seedance-2-0-260128、seedance-1-5-pro-251215、seedance-1-0-pro-250528、seedance-1-0-pro-fast-251015、seedance-1-0-lite-t2v-250428、seedance-1-0-lite-i2v-250428图像dola-seedream-5-0-pro-260628、seedream-5-0-260128、seedream-5-0-lite-260128、seedream-4-5-251128、seedream-4-0-250828两类 ID 均以(string {})收尾意味着类型层面允许任意自定义 ID为后续新模型留出兼容空间。二、版本主线从 1.0.0 到 2.0.42 的三大阶段CHANGELOG 完整记录了该包的发布轨迹可归纳为三个阶段1.x 初始化阶段1.0.0feat (provider/bytedance): initial bytedance provider——首个版本仅提供视频模型能力随后 1.0.11.0.4 均为依赖层面的小版本跟进ai-sdk/provider-utils4.0.x。v7 预发布阶段2.0.0-beta/canary 系列8359612: Start v7 pre-release开启 v7 预发布期间通过2.0.0-canary.33、2.0.0-beta.0、2.0.0-beta.20等迭代完成 ESM 改造ef992f8移除所有 CommonJS 导出、Node 版本门槛提升7fc6bd6最低 Node 22支持 22/24/26、Seedance 2.0 支持12d239b与首帧标记修复a2ad029。2.0.x 稳定演进阶段这是本文的论述重点涵盖异步视频任务协议2.0.21/2.0.27、Seedream 图像模型2.0.11、URL 安全加固2.0.10、Webhook 回调优先2.0.42等关键变更。2.1 2.0.0 的破坏性变更ESM-only 与 Node 222.0.0 标记为 Major Changes对消费方有两项硬性要求ESM-onlyRemove CommonJS exports from all packages. All packages are now ESM-only (type: module). Consumers using require() must switch to ESM import syntax.这与 package.json 中的type: module、exports字段仅暴露import/default条件一一对应Node 版本最低要求提升到 22官方支持 22、24、26。同版本还包含几个功能性 Patcha2ad029修复了「当提供尾帧图像时把提示图标记为第一帧」的请求体构造问题对应 bytedance-video-model.ts 中role: first_frame的条件添加逻辑12d239b为 Seedance 2.0 提供支持0416e3e为视频调用增加了一等公民的generateAudio选项。三、视频生成的异步化doStart/doStatus 取代内部轮询这是该包 2.0.x 阶段最核心的架构变革贯穿 2.0.21、2.0.27、2.0.36、2.0.39、2.0.42 五个版本。3.1 2.0.21引入异步 start/status 流程79e133c在实验性视频模型接口VideoModelV4上新增异步 API模型可实现doStart、doStatus、handleWebhookOption替代或补充原有的doGenerate单次轮询实现experimental_generateVideo新增poll与webhook两个选项用于编排完成流程轮询配置支持自定义延迟实现从而兼容 durable workflow持久化工作流场景——例如在重启后仍能恢复轮询节奏。从 bytedance-video-model.ts 可以看到doStart的实现向${baseURL}/contents/generations/tasks发起POST从响应中提取taskId返回{ operation: { taskId }, warnings, response }。而doStatus同文件 L393-L485则对${baseURL}/contents/generations/tasks/${taskId}发起GET依据status字段分派succeeded→ 返回completed与video/mp4视频 URLfailed/expired/cancelled/canceled→ 返回error终态其他 → 返回pending由上层继续轮询。3.2 2.0.27轮询职责上移与默认值变更8b6d615彻底移除了模型内部的doGenerate轮询循环Polling is now orchestrated bygenerateVideovia itspoll: { intervalMs, timeoutMs }option. ThepollIntervalMsandpollTimeoutMsprovider options are deprecated and ignored; passing either emits a warning. The polling defaults change accordingly (interval 3000ms to 5000ms, timeout 300000ms to 600000ms), and a failed or cancelled task now rejects with a plainErrorrather than anAISDKError. Failure reasons reported by the task are now included in the error message.对应到源码bytedance-video-model-options.tspollIntervalMs/pollTimeoutMs被标记为deprecatedbytedance-video-model.ts 中只要检测到这两个选项被传入就会产生一条deprecated类型的警告提示改用poll: { intervalMs, timeoutMs }。这是三层含义职责分离轮询节奏由 AI SDK 核心统一编排Provider 只负责「启动任务」与「查询状态」两个原语任何 Provider 的异步行为趋于一致默认值调整轮询间隔从 3000ms 放宽到 5000ms总超时从 300000ms5 分钟放宽到 600000ms10 分钟更贴合视频生成这类长耗时任务错误语义收敛失败/取消任务以普通Error拒绝且把任务上报的失败原因拼入错误信息——对应doStatus中的failureDetails回退逻辑L459-L474优先取error.message其次error.code都没有则JSON.stringify(statusResponse)兜底保证诊断信息永不丢失。3.3 2.0.36暴露尾帧 URL 到 providerMetadata99d4211将生成视频的尾帧 URL 暴露到 Provider 元数据中。在doStatus的completed分支L440-L448可以看到providerMetadata.bytedance携带taskId、usage含completion_tokens以及条件性出现的lastFrameUrl取自响应content.last_frame_url。尾帧 URL 可用于视频续接chaining场景与returnLastFrameProvider 选项形成呼应。3.4 2.0.39状态轮询重定向校验a580ec8为 MiniMax、Kling AI、ByteDance 三个 Provider 统一补齐「视频状态轮询重定向校验」。结合 2.0.10 的安全改造见下文第六节doStatus的getFromApi调用已启用validateUrl: true与trustedOrigin: this.config.baseURLL399-L413确保轮询目标与重定向链路始终处于可信范围内。3.5 2.0.42Webhook 回调优先与过期任务终态化最新版本带来两项行为收尾webhookUrl转发为callback_url且优先级最高doStart中若调用方传入webhookUrl直接写入请求体body.callback_url options.webhookUrlL352-L356覆盖 Provider 侧原始回调地址。测试用例bytedance-video-model.test.ts覆盖了四种组合仅 webhookUrl、仅原始 callback_url、两者皆无、两者皆有验证 webhookUrl 始终优先。注释同时说明本模型不实现handleWebhookOption因为进度通知需要协议感知的接收器protocol-aware receiver因此由调用方自持接收器、通过webhookUrl转发而generateVideo({ webhook })继续回退到轮询。过期任务视为终态错误expired状态与failed/cancelled/canceled并列L453-L458并以status: error 完整诊断信息返回而不是无限期 pending。测试L427-L452验证了expired分支及其错误信息格式。四、视频调用的完整实战从文本到多参考输入4.1 基础用法与 Provider 参数全表结合 README.md 与 bytedance-video-model-options.ts视频模型支持 text-to-video、image-to-video、audio-video sync、首尾帧控制、多参考图像/视频/音频生成。完整 Provider 参数如下参数类型说明watermarkboolean是否在生成视频上加水印generateAudioboolean是否为支持的 Seedance 模型同步生成音频cameraFixedboolean生成过程中是否固定机位returnLastFrameboolean返回视频尾帧便于链式续接serviceTierdefault \| flexdefault在线推理flex离线推理价格为 50%draftboolean草稿模式480p 低成本预览仅 Seedance 1.5 ProlastFrameImagestring首尾帧生成中的尾帧图片 URLreferenceImagesstring[]多参考图像 URL 数组referenceVideosstring[]参考视频 URL 数组referenceAudiostring[]参考音频 URL 数组pollIntervalMsnumber⚠️ 已废弃被忽略改用poll: { intervalMs }pollTimeoutMsnumber⚠️ 已废弃被忽略改用poll: { timeoutMs }文本转视频最小示例import { byteDance, type ByteDanceVideoModelOptions } from ai-sdk/bytedance; import { experimental_generateVideo as generateVideo } from ai; const { video } await generateVideo({ model: byteDance.video(seedance-1-0-pro-250528), prompt: A cat playing with a ball of yarn in a sunlit room, aspectRatio: 16:9, duration: 5, providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); console.log(video.url);4.2 请求体构造的底层映射从源码看请求体并非简单透传buildRequestBodyprompt写入content数组的text条目首帧图片来自options.image或frameImages中的first_frame写入image_url条目若同时提供尾帧首帧条目被标记role: first_frame尾帧写入role: last_frame对应 2.0.0 的a2ad029修复referenceImages/referenceVideos/referenceAudio分别映射为role: reference_image、reference_video、reference_audio条目2.0.8 起inputReferences也支持视频引用mediaType顶层类型为 video 时映射为video_urlaspectRatio→ 请求体ratioduration→durationseed→seedresolution经RESOLUTION_MAPL44-L85映射为480p/720p/1080p等级generateAudio选项顶层或 Provider 内→ 请求体generate_audiowatermark、camera_fixed、return_last_frame、service_tier、draft依此类推未被HANDLED_PROVIDER_OPTIONS覆盖的任意选项会原样透传到请求体为未来 API 字段留出前向兼容。4.3 已知限制与警告机制实现层面刻意声明了三类限制调用时会以warnings返回而不是抛错不支持自定义 FPS帧率固定 24fpsL216-L223不支持单次多视频maxVideosPerCall 1n 1时警告并只生成 1 个视频L225-L233URL 引用必须显式声明 mediaType否则按图像处理并给出unsupported警告L121-L137。4.4 首尾帧、音频同步与多参考实战首尾帧 音频同步const { video } await generateVideo({ model: byteDance.video(seedance-1-5-pro-251215), prompt: { image: https://example.com/first-frame.jpg, text: Create a 360-degree orbiting camera shot based on this photo, }, duration: 5, providerOptions: { bytedance: { lastFrameImage: https://example.com/last-frame.jpg, generateAudio: true, watermark: false, } satisfies ByteDanceVideoModelOptions, }, });多参考图像Seedance 1.0 Lite i2v14 张提示词中用[Image 1]、[Image 2]等占位引用const { video } await generateVideo({ model: byteDance.video(seedance-1-0-lite-i2v-250428), prompt: A boy from [Image 1] and a corgi from [Image 2], sitting on the lawn from [Image 3], aspectRatio: 16:9, duration: 5, providerOptions: { bytedance: { referenceImages: [ https://example.com/boy.png, https://example.com/corgi.png, https://example.com/lawn.png, ], watermark: false, } satisfies ByteDanceVideoModelOptions, }, });支持的宽高比16:9、4:3、1:1、3:4、9:16、21:9以及 image-to-video 专用的adaptive。五、Seedream 图像模型2.0.11 的里程碑能力7fd7dab为该包补齐了图像生成能力通过.image()/.imageModel()创建 Seedream 模型并引入类型化的ByteDanceImageModelOptions。5.1 Provider 参数全表来自 bytedance-image-model-options.ts参数类型说明watermarkboolean输出图像右下角是否添加 AI generated 水印outputFormatpng \| jpeg输出格式seedream-5-0/dola-seedream-5-0-pro支持seedream-4-5/seedream-4-0固定返回 jpegsizestring分辨率等级如1K/2K/3K/4K设置后覆盖顶层size像素尺寸参数可用等级因模型而异sequentialImageGenerationauto \| disabledauto时批量生成一组关联图像故事板/品牌视觉默认disabled单张maxImagesnumbersequentialImageGeneration: auto时的最大生成数量输入参考图数 生成数不得超过模型上限optimizePromptModestandard \| fast提示词优化模式seedream-4-0两种都支持其余模型仅standard5.2 实现要点与 Token 用量上报bytedance-image-model.ts 揭示了几个关键实现事实单次调用恒返回一张图maxImagesPerCall 1因为 API 没有输出数量参数generateImage的n参数由 AI SDK 核心扇出为n次调用。批量关联图只能通过sequentialImageGeneration实现L40-L44强制b64_json响应格式body.response_format b64_json不可被用户覆盖SDK 始终拿到图片字节L155-L157不支持 aspectRatio / seed / mask均以unsupported警告返回mask 场景官方建议「在提示词中描述编辑指令或在输入图上做标记」L70-L92Token 用量上报2.0.315b7da0emapImageUsage将响应的usage.output_tokens/usage.total_tokens映射为ImageModelV4Usage使图像生成同样进入 AI SDK 的用量统计体系L184-L194响应 Schema 最小化只解析data[].b64_json与usage降低 API 新增字段时的破坏风险L196-L206。六、安全加固getFromApi 的 URL 校验体系2.0.104be62c1是 2.0.10 的安全大版本虽属于ai-sdk/provider-utils的变更但 ByteDance 包作为所有调用方之一「在每个调用点显式做出可信决策」getFromApi新增validateUrl标志。为true时URL 经过fetchWithValidatedRedirects守卫拒绝 private / loopback / link-local 目标重定向逐跳重新校验剥离 proxy/metadata/cookie 请求头跨源重定向时丢弃除 user-agent 外的所有调用方请求头自定义 API-key 头不得跟随重定向离开源站与Authorization同等对待被拦截的 URL 抛出DownloadError新增可选credentialedOrigin除非 URL 与该 origin 同源否则不携带调用方请求头防止 API key 被发送到响应方提供的异源主机新增可选trustedOrigin与开发者配置的 Provider 端点同源的 URL含重定向跳豁免目标校验保证自托管与 localhost 部署可用其余跳仍逐跳校验补充了validateDownloadUrl的网段覆盖IPv4 组播224.0.0.0/4、TEST-NET 文档网段、IPv6 文档网段2001:db8::/32、3fff::/20且只跟随 fetch 规范的重定向状态码 301/302/303/307/308。在 ByteDance 视频模型中的落地点正是doStatus的轮询请求getFromApi({ ..., validateUrl: true, trustedOrigin: this.config.baseURL })——响应体提供的下载/轮询 URL 全部走校验而基于开发者配置端点拼接的 URLdoStart的postJsonToApi不受影响。守卫仅做字符串/字面量检查、不解析 DNS解析到私网地址的主机名与 DNS rebinding 不在其范围内面向不可信 URL 的服务端部署需在网络层或注入固定解析 IP 的 Nodefetch另行约束详见 contributing/secure-url-handling.md。七、类型命名与兼容性策略2.0.8 的b0650cb修正了命名不一致ByteDanceVideoProviderOptions更名为ByteDanceVideoModelOptions。为保护既有代码index.ts 保留旧名作为deprecated 别名export type { ByteDanceVideoModelOptions, /** deprecated Use ByteDanceVideoModelOptions instead. */ ByteDanceVideoModelOptions as ByteDanceVideoProviderOptions, } from ./bytedance-video-model-options;这是 AI SDK Provider 包惯用的「重命名 别名过渡」策略新代码用新名旧代码在编译期获得弃用提示而非直接断裂。八、工程化与发布实践CHANGELOG 尾部还记录了若干工程化细节38fc777在 Provider README 中补充 AI Gateway 提示9f0e36c在 provenance 配置就绪后触发全量发布对应 package.json 的provenance: true0c4c275/b8396f0分别为 canary / beta 初始发布258c093统一导入处理、避免循环依赖ba6d510修复 zod.passthrough()的弃用用法。测试方面包内同时维护 vitest.node 与 vitest.edge 双配置见 vitest.node.config.js 与 vitest.edge.config.js视频/图像模型各有独立测试文件覆盖doStart请求体构造、doStatus状态分派、Webhook 优先级等关键路径。九、快速开始安装与认证安装npm i ai-sdk/bytedance认证二选一# 方式一环境变量默认 export ARK_API_KEYyour-api-key// 方式二显式传入createByteDance 返回可配置实例 import { createByteDance } from ai-sdk/bytedance; const byteDance createByteDance({ apiKey: your-api-key, });createByteDance还接受baseURL默认https://ark.ap-southeast.bytepluses.com/api/v3、headers、fetch三个高级配置bytedance-provider.ts。默认导出实例byteDance即createByteDance()的零配置产物请求头统一为Authorization: Bearer ARK_API_KEYContent-Type: application/json。十、版本变更速查版本变更哈希核心内容1.0.015a9e21初始 ByteDance Provider视频2.0.0ef992f8/8359612等ESM-only、v7 预发布、Node 22、Seedance 2.0、首帧标记修复、generateAudio 选项2.0.30274f34视频frameImages/inputReferences一等公民选项2.0.8b0650cb/0f93c57选项类型重命名保留别名inputReferences 支持视频引用2.0.104be62c1getFromApi URL 校验validateUrl / credentialedOrigin / trustedOrigin2.0.117fd7dabSeedream 图像模型.image()/.imageModel()2.0.2179e133cVideoModelV4 异步 start/status 流程generateVideo 的 poll / webhook 选项2.0.278b6d615移除 doGenerate 内部轮询轮询默认 5000ms / 600000ms错误语义收敛2.0.315b7da0e图像生成 Token 用量上报2.0.3699d4211providerMetadata 暴露尾帧 URL2.0.39a580ec8视频状态轮询重定向校验MiniMax / Kling AI / ByteDance2.0.42ef3bac4webhookUrl 优先转发 callback_urlexpired 视为终态错误结语从initial bytedance provider到webhookUrl优先级与expired终态化ai-sdk/bytedance的 CHANGELOG 完整呈现了一个视频/图像 Provider 在异步协议、安全模型、类型工程上的成熟轨迹。对开发者而言理解doStart/doStatus分工与poll/webhook编排方式是正确使用 Seedance 长耗时生成任务的关键而validateUrltrustedOrigin的安全设计则为自托管与 Serverless 部署提供了可预期的信任边界。本文所述全部行为均可在仓库源码与测试中复现验证进一步阅读可直达 视频模型测试 与 图像模型测试。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
