使用 AI SDK 的 Black Forest Labs Provider 生成图像与视频完整接入指南【免费下载链接】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 SDKThe AI Toolkit for TypeScript的ai-sdk/black-forest-labs包为主体讲解如何通过统一的高层 APIgenerateImage、experimental_generateVideo接入 Black Forest Labs 的 FLUX 系列图像与视频模型涵盖安装、Provider 实例配置、模型选择、进阶参数、轮询机制与安全细节。读完本文你将掌握在任意 TypeScript/Node.js 项目中调用flux-pro-1.1、flux-kontext-pro、flux-3-video等模型并落地生产级生成任务的完整方案。概览与前置准备ai-sdk/black-forest-labs是 AI SDK 官方的 Black Forest Labs Provider 实现为 Black Forest Labs API 目录对应的发布包。从 package.json 可以看到该包运行时仅依赖ai-sdk/provider与ai-sdk/provider-utils两个内部工具包Peer 依赖zod^3.25.76 || ^4.1.8并声明node 22。接入前你还需要一个 Black Forest Labs API Key可通过环境变量BFL_API_KEY提供安装了aiAI SDK 主包与ai-sdk/black-forest-labs的 TypeScript 项目。安装 Provider使用 pnpm仓库本身即 pnpm workspace见 pnpm-workspace.yaml安装pnpm add ai-sdk/black-forest-labs如果使用其他包管理器等价命令为npm install ai-sdk/black-forest-labs或yarn add ai-sdk/black-forest-labs。创建 Provider 实例Provider 提供了两种使用方式默认实例直接导入blackForestLabsAPI Key 自动从环境变量BFL_API_KEY读取自定义实例通过createBlackForestLabs显式配置可覆盖 Base URL、API Key、请求头、自定义 fetch 与轮询参数。import { blackForestLabs } from ai-sdk/black-forest-labs; // 默认实例自动读取 process.env.BFL_API_KEY const { image } await generateImage({ model: blackForestLabs.image(flux-pro-1.1), prompt: A cat wearing an intricate robe, });从 black-forest-labs-provider.ts 的源码可见createBlackForestLabs内部通过loadApiKey读取options.apiKey缺省时回退到名为BFL_API_KEY的环境变量并在每个请求头中注入x-key以及形如ai-sdk/black-forest-labs/version的 User-Agent 后缀方便服务端识别 SDK 版本。Provider 实例暴露以下方法方法返回类型说明image(modelId)/imageModel(modelId)ImageModelV4创建图像生成模型video(modelId)/videoModel(modelId)Experimental_VideoModelV4创建视频生成模型languageModel(modelId)抛NoSuchModelError该 Provider 不提供语言模型embeddingModel(modelId)/textEmbeddingModel(modelId)抛NoSuchModelError该 Provider 不提供 Embedding 模型也就是说blackForestLabs只负责图像与视频两类能力调用语言/Embedding 方法会抛出NoSuchModelError见 black-forest-labs-provider.ts。图像生成从文本到 PNG图像生成的入口是 AI SDK 的generateImage配合blackForestLabs.image(modelId)import fs from node:fs; import { blackForestLabs } from ai-sdk/black-forest-labs; import { generateImage } from ai; const { image } await generateImage({ model: blackForestLabs.image(flux-pro-1.1), prompt: A cat wearing a intricate robe, }); const filename image-${Date.now()}.png; fs.writeFileSync(filename, image.uint8Array); console.log(Image saved to ${filename});generateImage返回的image对象包含uint8Array原始图片字节直接写入文件即可得到图片同时它还携带mimeType等信息。支持的图像模型 ID根据 black-forest-labs-image-settings.ts当前内置的模型 ID 包括模型 ID定位flux-kontext-proFLUX.1 Kontext [pro]同时接收文本与参考图像输入支持定向编辑与复杂变换flux-kontext-maxFLUX.1 Kontext [max]更强的提示词遵循与排版/字形生成能力flux-pro-1.1-ultra超快、超高分辨率的图像创建flux-pro-1.1快速、高质量的文生图flux-pro-1.0-fill图像填充/编辑inpainting场景BlackForestLabsImageModelId类型还带有(string {})兜底意味着你也能传入 BFL API 后续新增的模型 ID。顶层参数与宽高比generateImage顶层可传prompt、aspectRatio、size、seed、files参考图像与mask蒙版用于 inpaint。其中宽高比类型定义为${number}:${number}如16:9、1:1。值得注意的一个实现细节见 black-forest-labs-image-model.ts当你同时传入size与aspectRatio时SDK 会忽略size并发出unsupported警告——BFL 只认aspect_ratio而只传size时SDK 会用最大公约数算法convertSizeToAspectRatio把1024x1024之类的尺寸换算成最简宽高比再映射为 BFL 的aspect_ratio参数并同样发出提示。如果你需要精确控制像素尺寸应使用下方providerOptions中的width/height。参考图像与蒙版files参数可携带最多 10 张参考图像源码在 black-forest-labs-image-model.ts 中对此做了显式校验超过会抛出Black Forest Labs supports up to 10 input images.。每张图可以是 URL、base64 字符串或Uint8Array字节mask同理。底层会将它们映射为 BFL API 的input_image/input_image_2… 字段对于flux-pro-1.0-fill模型则映射为image字段见 black-forest-labs-image-model.ts。视频生成文本/图生视频视频生成使用 AI SDK 的实验性 APIexperimental_generateVideoimport { blackForestLabs } from ai-sdk/black-forest-labs; import { experimental_generateVideo as generateVideo } from ai; const { video } await generateVideo({ model: blackForestLabs.video(flux-3-video), prompt: A white kitten chases a butterfly across a sunlit garden., aspectRatio: 16:9, duration: 8, });支持的视频模型与参数约束当前视频模型 ID 为flux-3-video见 black-forest-labs-video-settings.ts支持最高全高清、最长 20 秒并带同步音频覆盖文生视频t2v、关键帧图生视频i2v与视频续写v2v三种模式。源码对视频参数做了严格的归一化处理见 black-forest-labs-video-model.tsduration必须是 520 秒之间的整数秒非整数会被四舍五入并发出警告超出范围会被钳制到边界值aspectRatio仅接受21:9、2:1、16:9、4:3、1:1、3:4、9:16与auto八种取值auto由模型根据提示词与条件媒体自行推断也是 API 默认值resolution仅接受命名档位hd720p 级与fhd1080p 级如果顶层传入1920x1080这类{width}x{height}值SDK 会按较短边自动映射到对应档位并给出compatibility提示见 black-forest-labs-video-model.tsfps / seedflux-3-video不支持自定义帧率与种子传入会被忽略并产生unsupported警告单次调用只生成一个视频maxVideosPerCall 1n 1时仅返回 1 个视频。进阶参数providerOptions.blackForestLabs除prompt外的模型专属输入通过providerOptions.blackForestLabs传入SDK 会先用 zod schema 校验再序列化到 BFL API见 black-forest-labs-image-model-options.ts 与 black-forest-labs-video-model-options.ts。图像专属参数import { blackForestLabs, type BlackForestLabsImageProviderOptions, } from ai-sdk/black-forest-labs; import { generateImage } from ai; const { image } await generateImage({ model: blackForestLabs.image(flux-pro-1.1), prompt: A cat wearing an intricate robe, aspectRatio: 16:9, providerOptions: { blackForestLabs: { outputFormat: png, } satisfies BlackForestLabsImageProviderOptions, }, });可用字段与约束依据 black-forest-labs-image-model-options.ts字段类型/取值范围说明imagePromptstring独立的图像提示词imagePromptStrengthnumber01图像提示强度steps正整数采样步数guidancenumber ≥ 0引导系数width/height整数2561920输出像素尺寸与顶层aspectRatio二选一使用outputFormatjpeg \| png输出格式promptUpsamplingboolean是否启用提示词上采样rawboolean返回未处理输出safetyTolerance整数 06内容审核宽容度0 最严格webhookSecret/webhookUrlstring / URL异步完成通知pollIntervalMillis/pollTimeoutMillis正整数单次请求级轮询覆盖见下文另外inputImageinputImage10字段已被标记为deprecated请改用顶层prompt.images。视频专属参数const { video } await generateVideo({ model: blackForestLabs.video(flux-3-video), prompt: A white kitten chases a butterfly across a sunlit garden., providerOptions: { blackForestLabs: { aspectRatio: auto, resolution: fhd, draft: false, }, }, });视频专属字段依据 black-forest-labs-video-model-options.ts字段类型/取值范围说明resolutionhd \| fhd输出档位优先级高于顶层resolutionaspectRatio八种预设或auto宽高比优先级高于顶层aspectRatiokeyframes字符串数组 或[秒数, 图片]元组数组110 个关键帧1 张开启片段、2 张分别开启/收尾更多则均匀间隔时间戳必须严格递增schema 内置校验3 张及以上无时间戳的关键帧必须显式指定durationsafetyTolerance整数 04默认 2审核宽容度性内容上限 3、仇恨内容上限 2携带条件媒体时上限 2draftboolean默认 false先生成快速低质量预览draftCachestring之前draft生成的加密缓存包base64 的.bin或其 URL传入即切换为draft-enhance 模式以全质量重放该缓存包versionlatest固定模型版本当前仅有latestdraft-enhance 模式的行为很特殊缓存包会固定原始的模式、提示词、种子与条件媒体因此除safety_tolerance外的所有参数都会被忽略SDK 会为每一个被忽略的已设置参数输出unsupported警告见 black-forest-labs-video-model.ts。配置 Base URL区域与兼容端点默认 Base URL 为https://api.bfl.ai/v1常量定义于 black-forest-labs-provider.ts。如需使用区域端点或旧版端点通过createBlackForestLabs覆盖import { createBlackForestLabs } from ai-sdk/black-forest-labs; const blackForestLabs createBlackForestLabs({ baseURL: https://api.eu.bfl.ai/v1, apiKey: process.env.BFL_API_KEY, });createBlackForestLabs支持的完整配置项见 black-forest-labs-provider.ts配置项默认值说明apiKey环境变量BFL_API_KEYAPI Key注入x-key请求头baseURLhttps://api.bfl.ai/v1API 基础地址headers—追加的自定义请求头fetch全局 fetch自定义 fetch 实现可用于拦截请求或测试pollIntervalMillis图片 500ms / 视频 2s轮询间隔pollTimeoutMillis图片 60s / 视频 10 分钟轮询总超时配置轮询默认值、全局覆盖与单请求覆盖Black Forest Labs 的生成任务采用提交 → 轮询 → 取结果的异步模型SDK 内部封装了完整的轮询逻辑。默认参数按模型类型区分图像每 500ms 轮询一次60 秒超时视频每 2 秒轮询一次10 分钟超时。两个默认值分别定义于 black-forest-labs-image-model.ts 与 black-forest-labs-video-model.ts。全局覆盖Provider 级import { createBlackForestLabs } from ai-sdk/black-forest-labs; const blackForestLabs createBlackForestLabs({ apiKey: process.env.BFL_API_KEY, // 每 500ms 轮询一次5 分钟后超时 pollIntervalMillis: 500, pollTimeoutMillis: 5 * 60_000, });单请求覆盖请求级通过providerOptions.blackForestLabs传入即可只影响当前这一次调用import { blackForestLabs } from ai-sdk/black-forest-labs; import { generateImage } from ai; const { image } await generateImage({ model: blackForestLabs.image(flux-pro-1.1), prompt: A cat wearing an intricate robe, providerOptions: { blackForestLabs: { pollIntervalMillis: 250, pollTimeoutMillis: 30_000, }, }, });优先级为请求级providerOptions Provider 级配置 模型类型默认值。图像的轮询实现会先计算maxPollAttempts ceil(pollTimeoutMillis / max(1, pollIntervalMillis))在到达最大次数前持续查询状态为Ready时取result.sample返回图片 URLError/Failed时抛出生成失败错误超时则抛出Black Forest Labs generation timed out.见 black-forest-labs-image-model.ts。视频模型的轮询doGenerate内部循环在超时时抛出BLACK_FOREST_LABS_VIDEO_GENERATION_TIMEOUT错误并携带 request id 便于排查见 black-forest-labs-video-model.ts。轮询过程中可能出现的状态包括Pending、Ready、Error、Failed、Request Moderated图像以及视频侧的Content Moderated、Task not found等终态失败状态。底层原理一次完整的生成调用链结合源码可以还原一次图像生成的完整数据流参数归一化generateImage将顶层参数prompt、aspectRatio、files、mask、seed 等与providerOptions.blackForestLabs合并映射为 BFL API 请求体aspect_ratio、width、height、steps、guidance、output_format、safety_tolerance等提交任务POST {baseURL}/{modelId}携带x-key与 User-Agent 头返回{ id, polling_url, cost, input_mp, output_mp }见 black-forest-labs-image-model.ts轮询状态循环 GETpolling_url?id{requestId}直到Ready下载图片从result.sample指向的 URL 以二进制方式拉取图片字节作为image.uint8Array返回结果元数据providerMetadata.blackForestLabs.images[0]中回传seed、start_time、end_time、duration、cost、inputMegapixels、outputMegapixels等字段方便做计费与可观测见 black-forest-labs-image-model.ts。视频链路采用doStart提交→doStatus查询→doGenerate聚合的三段式实现其中doStatus在Ready时通过 zod 校验result.sample并返回video/mp4的 URL 结果见 black-forest-labs-video-model.ts。安全细节凭据只发给可信主机BFL 的响应里会返回轮询地址与图片/视频下载地址它们可能位于 API 主机的兄弟集群域名例如 Base URL 为api.bfl.ai时结果可能落在api.us1.bfl.ai因此 SDK 不能只做严格的同源校验。isTrustedUrl见 black-forest-labs-api.ts的判定规则是与配置的 Base URL 同源或位于https://协议下且主机名为bfl.ai及其任意子域。只有命中该规则时SDK 才会在轮询与下载请求中携带x-key等凭据头图片通常由 CDN 提供此时 API Key 绝不会被发送到外部主机见 black-forest-labs-image-model.ts。测试与验证仓库在 black-forest-labs-provider.test.ts 与 black-forest-labs-image-model.test.ts、black-forest-labs-video-model.test.ts 中提供了完整的测试用例使用ai-sdk/test-server模拟了提交 → 轮询返回 Ready → 下载图片/视频的完整服务端行为。你可以直接运行cd packages/black-forest-labs pnpm test来验证 Provider 的端到端行为是否符合预期测试同时覆盖 node 与 edge 环境对应vitest.node.config.js与vitest.edge.config.js。进一步阅读完整文档位于 content/providers/01-ai-sdk-providers/12-black-forest-labs.mdx其中包含各模型的详细定位说明与更多端到端示例Provider 的公共类型导出见 packages/black-forest-labs/src/index.tscreateBlackForestLabs、blackForestLabs、BlackForestLabsProvider、BlackForestLabsProviderSettings以及图像/视频的模型 ID 与 Options 类型变更记录可查阅 packages/black-forest-labs/CHANGELOG.md了解各版本行为变化若使用 Claude Code、Cursor 等编码 Agent 辅助开发可将 AI SDK 技能加入仓库以获取最新的使用指引。至此你已经可以从安装、配置、文生图、文生视频到进阶参数调优与生产级轮询/安全细节完整地在自己的 TypeScript 项目中接入 Black Forest Labs 的图像与视频生成能力。【免费下载链接】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），仅供参考
