AI SDK Replicate 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-sdk/replicate是 AI SDKThe AI Toolkit for TypeScript中对接 Replicate API 的官方 Provider 包专注提供 Replicate 云端模型的图像生成与视频生成能力。本文以该包的 CHANGELOG 为核心脉络结合包内源码系统梳理其从 0.0.1 到 3.0.40 的关键演进——包括可配置同步等待时长的图像生成、基于轮询与 Webhook 的异步视频生成、响应 URL 安全校验、v7 主版本的 ESM-only 迁移等并给出可复制、可运行的实战代码。读完本文你将掌握如何安装并实例化 Replicate Provider、如何用generateImage完成文生图与图生图、如何用experimental_generateVideo编排异步视频任务以及如何在生产环境正确配置认证与安全边界。一、包定位与版本演进主线从 CHANGELOG 可以看到ai-sdk/replicate经历了清晰的演进0.0.1初始发布feat (provider/replicate): add replicate image provider从图像生成起步0.1.x 阶段支持版本化模型versioned models、图像模型规范ImageModelV2、maxImagesPerCall设置1.0.0AI SDK 5ImageModelV1更名为ImageModelV2图像模型设置迁入generateImage调用参数2.0.0AI SDK 6引入Provider-V3、ImageModelV3、specificationVersion并新增maxWaitTimeInSeconds同步等待配置与图像编辑image editing支持3.0.0AI SDK 7全面迁移到ProviderV4/ImageModelV4/VideoModelV4类型移除 CommonJS 导出、全部 ESM-onlyNode.js 最低版本提升到 22并加入工作流workflow序列化支持。当前包版本为 3.0.40对应依赖ai-sdk/provider4.0.13与ai-sdk/provider-utils5.0.39声明于 package.json。engines字段要求 Node.js22并仅提供 ESM 导出type: module。二、安装与 Provider 实例化按 README 的说明安装npm i ai-sdk/replicate包本身依赖ai-sdk/provider与ai-sdk/provider-utilsworkspace 依赖并将zod^3.25.76 || ^4.1.8声明为 peer 依赖见 package.json。Provider 的创建逻辑位于 replicate-provider.ts核心要点默认 API 地址为https://api.replicate.com/v1可通过baseURL覆盖例如接入代理或自托管网关API Token 通过Authorization: Bearer token头携带默认读取环境变量REPLICATE_API_TOKEN可通过apiToken显式传入所有请求自动追加ai-sdk/replicate/VERSION的 user-agent 后缀withUserAgentSuffix配合 version.ts 中的版本号Provider 暴露image/imageModel图像与video/videoModel视频两组工厂方法languageModel与embeddingModel会抛出NoSuchModelError即该包不提供文本对话与向量嵌入能力。常用配置示例import { createReplicate } from ai-sdk/replicate; const replicate createReplicate({ apiToken: process.env.REPLICATE_API_TOKEN, baseURL: https://api.replicate.com/v1, // 可选默认值 headers: { X-Custom-Header: value }, // 可选自定义请求头 fetch: customFetch, // 可选自定义 fetch 实现 });默认实例replicate直接可用无需任何参数replicate-provider.ts。三、图像生成从文生图到多图输入的 Flux-23.1 基础用法按 README 的示例一条文生图请求如下import { replicate } from ai-sdk/replicate; import { generateImage } from ai; const { image } await generateImage({ model: replicate.image(black-forest-labs/flux-schnell), prompt: The Loch Ness Monster getting a manicure, }); const filename image-${Date.now()}.png; fs.writeFileSync(filename, image.uint8Array); console.log(Image saved to ${filename});replicate.image()的 modelId 类型定义于 replicate-image-settings.ts内置了三类常见模型 ID文生图模型black-forest-labs/flux-1.1-pro、flux-pro、flux-dev、flux-schnell以及bytedance/sdxl-lightning-4step、luma/photon、nvidia/sana、stability-ai/stable-diffusion-3.5-*、recraft-ai/recraft-v3等修复/图像编辑模型black-forest-labs/flux-fill-pro、flux-fill-devFlux-2 系列black-forest-labs/flux-2-pro、flux-2-dev支持最多 8 张参考图。由于类型声明带有(string {})兜底你也可以传入任意其它 Replicate 模型 ID。3.2 传入模型特有参数除 prompt 外的额外输入通过providerOptions.replicate传递READMEconst { image } await generateImage({ model: replicate.image(recraft-ai/recraft-v3), prompt: The Loch Ness Monster getting a manicure, size: 1365x1024, providerOptions: { replicate: { style: realistic_image, }, }, });providerOptions的解析由 replicate-image-model-options.ts 中的 zod schema 完成z.looseObject允许透传任何模型特有字段同时为常见参数提供类型校验参数类型说明maxWaitTimeInSeconds正数同步模式最大等待秒数详见 3.4guidance_scalenumber无分类器引导强度越大越贴近提示词num_inference_stepsnumber去噪步数越多质量越高但越慢negative_promptstring反向提示词output_formatpng \| jpg \| webp输出图片格式output_quality1–100输出质量仅对 jpg/webp 生效strength0–1img2img 变换强度越低越保留原图3.3 图生图与 Flux-2 多图输入在 replicate-image-model.ts 的doGenerate实现中图像输入被转换为 Data URI 后写入请求体非 Flux-2 模型使用单数参数image仅取第一张输入图多余的图会产生SharedV4Warning警告并被忽略Flux-2 模型正则^black-forest-labs\/flux-2-匹配使用input_image、input_image_2…input_image_8支持最多 8 张参考图超出部分忽略并告警mask 输入非 Flux-2 模型映射为mask参数配合flux-fill-*等模型可实现修复/inpaintingFlux-2 模型不支持 mask会给出忽略警告。这一设计直接体现在maxImagesPerCall上Flux-2 模型为 8其余模型为 1replicate-image-model.ts。3.4 maxWaitTimeInSeconds可控的同步等待2.0.0 版本引入CHANGELOGd0920f9的maxWaitTimeInSeconds用于控制 Replicate 预测的同步等待时长对应请求头Prefer的两种取值见 replicate-image-model.ts未指定使用默认 60 秒同步等待发送Prefer: wait设为正数发送Prefer: waitN可延长同步超时以等待耗时更长的预测完成。await generateImage({ model: replicate.image(black-forest-labs/flux-1.1-pro), prompt: a cinematic sunset over a futuristic city, providerOptions: { replicate: { maxWaitTimeInSeconds: 120 }, // 等待最长 120 秒 }, });3.5 图像结果下载与 URL 校验doGenerate通过postJsonToApi提交预测版本化模型走/predictions非版本化模型走/models/{modelId}/predictionsbody 中额外携带version字段随后对响应output中的每个 URL 使用getFromApi下载二进制内容replicate-image-model.ts。3.0.10 版本CHANGELOG4be62c1为该下载调用显式开启了validateUrl: true并设置trustedOrigin为开发者配置的 baseURL——这是 3.0.0 中同源凭证修复aeda373的延续详见第五节安全章节。四、视频生成基于轮询与 Webhook 的异步编排4.1 支持的视频模型replicate-video-settings.ts 内置了两个视频模型 ID含版本化形式minimax/video-01及其固定版本minimax/video-01:6c1e4171-...stability-ai/stable-video-diffusion:3f0457e4-...ReplicateVideoModel的maxVideosPerCall恒为 1即每次调用生成一段视频replicate-video-model.ts。4.2 异步 APIdoStart / doStatus / handleWebhookOption3.0.20 版本CHANGELOG79e133c为实验性视频模型接口VideoModelV4引入了异步 start/status 流程模型可实现doStart、doStatus、handleWebhookOption替代或补充原有的doGenerate上层experimental_generateVideo接受poll与webhook选项来编排完成。在 replicate-video-model.ts 的实现中doStart向 Replicate 提交input含 prompt、image、aspect_ratio、size、duration、fps、seed 等版本化模型同样走/predictions并携带version若上层提供了webhookUrl会自动追加webhook与webhook_events_filter: [completed]。返回的operation.getUrl即响应的urls.get轮询地址doStatus对urls.get发起getFromApi同样开启validateUrl: true根据 prediction 的status分支处理failed/canceled→ 返回error状态及错误信息succeeded→ 返回completed状态携带视频 URL 与video/mp4媒体类型同时通过providerMetadata.replicate透出videos、predictionId、metrics.predict_timestarting/processing→ 返回pending状态等待下一次轮询handleWebhookOption接收上层提供的webhook()回调返回{ webhookUrl, received }供doStart拼入请求体。import { experimental_generateVideo } from ai; import { replicate } from ai-sdk/replicate; const result await experimental_generateVideo({ model: replicate.video(minimax/video-01), prompt: A jellyfish floating in a neon-lit ocean, // 方式一轮询可自定义延迟实现以适配持久化工作流 poll: { intervalMs: 5_000, timeoutMs: 300_000, }, // 方式二Webhook 回调 webhook: async () ({ url: https://example.com/webhook/replicate, secret: process.env.WEBHOOK_SECRET!, }), });视频模型特有的providerOptions.replicate参数定义于 replicate-video-model-options.ts参数说明pollIntervalMs/pollTimeoutMs轮询间隔与超时毫秒maxWaitTimeInSeconds同步等待上限guidance_scale/num_inference_steps通用生成参数motion_bucket_id/cond_aug/decoding_t/video_length/sizing_strategy/frames_per_secondStable Video Diffusion 专用参数prompt_optimizerMiniMax 专用布尔其它键通过 passthrough 透传这些参数在buildInput中被逐项映射为请求体的input字段未识别的键也会被透传replicate-video-model.ts。五、安全加固凭证同源与响应 URL 校验Replicate Provider 的安全演进是 CHANGELOG 中反复出现的主题也值得在生产接入时重点了解。3.0.0aeda373——凭证只发送给同源响应 URL。此前多个 Provider 客户端会直接跟随 API 响应体返回的 URL如polling_url、urls.get、result_url、video.uri等并复用携带 API Key 的认证头或追加?keyAPI_KEY查询参数。由于响应 URL 的主机未经验证一旦响应被篡改长期有效的 API Key 可能被发送到攻击者指定的主机造成凭证泄露。修复方式是ai-sdk/provider-utils新增isSameOrigin辅助函数ai-sdk/replicate等六个 Provider 仅在与配置的 API 源同源时才附加凭证跨源请求不带凭证。3.0.104be62c1——下载与轮询 URL 校验。getFromApi新增validateUrl标志开启后请求经fetchWithValidatedRedirects处理拒绝私网/回环/链路本地地址重新校验每一次重定向跳转剥离代理/元数据/Cookie 请求头跨源重定向时丢弃除 user-agent 外的全部调用方头自定义 API-Key 头不得随重定向出域与Authorization同等对待被拦截的 URL 抛出DownloadError。同时新增两个可选参数credentialedOrigin仅当 URL 与该源同源时才携带调用方头防止 API Key 被发送到响应指定主机trustedOrigin与开发者配置的 Provider 端点同源的 URL含重定向跳豁免目标校验保证自托管/localhost 部署响应 URL 指向配置主机仍可工作其余跳转照常校验。在源码中图像下载replicate-image-model.ts与视频状态轮询replicate-video-model.ts都已显式开启validateUrl: true后者同时设置了credentialedOrigin与trustedOrigin。该修复还补齐了validateDownloadUrl的 IPv4/IPv6 文档网段192.0.2.0/24、2001:db8::/32等并只跟随 fetch 规范定义的重定向状态码301/302/303/307/308。需要说明的是该防护只做字符串/字面量检查、不解析 DNS主机名解析到私网地址与 DNS rebinding 仍需在网络层约束或注入在连接时固定解析 IP 的 Nodefetch。详细背景可参考 secure-url-handling.md。3.0.10cd12954——空 baseURL 校验。对 OpenAI、Anthropic 与 Replicate 的空baseURL现在会抛出明确的 AI SDK invalid argument 错误而不是静默失败。对应实现是validateBaseURL见 replicate-provider.ts。六、v7 主版本的关键变更3.0.0含 3.0.0-beta.x / canary 阶段集中了 v7 大版本的多项 breaking changesESM-onlyef992f8移除全部 CommonJS 导出使用require()的消费者必须迁移到 ESMimport语法Node.js 227fc6bd6最低支持版本提升至 22支持 22、24、26Provider V4 类型c434fd2provider/replicate更新为 v4 类型Provider 的specificationVersion为v4见 replicate-provider.ts工作流序列化b3976a2ai-sdk/provider-utils新增serializeModel()帮助函数headers在 Provider 配置类型中变为可选所有 Provider 模型类实现WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法使模型实例能够跨工作流步骤边界序列化而不报错。ReplicateImageModel中可以看到这两个方法的实现replicate-image-model.ts符号重命名04e9009统一各 Provider 实现模式被重命名的导出符号保留 deprecated 别名以兼容旧代码AI Gateway 提示38fc777与包元数据/发布流程调整9f0e36cprovenance 溯源、0c4c275canary 发布、b8396f0beta 发布。此外2.0.0 中EmbeddingModelV3移除了泛型参数textEmbeddingModel→embeddingModel并新增specificationVersion到ProviderV3这些都为 v4 的统一奠定了基础。七、在 AI SDK 中组合使用Replicate Provider 可以与 AI SDK 的其余部分自由组合。例如将 Replicate 图像模型与语言模型 Agent 串联先由文本模型生成提示词再交给replicate.image()产出图片。典型的最小完整示例import { replicate } from ai-sdk/replicate; import { generateImage } from ai; import fs from node:fs; // REPLICATE_API_TOKEN 必须已在环境中配置 const { image } await generateImage({ model: replicate.image(black-forest-labs/flux-schnell), prompt: A tiny robot painting a watercolor landscape, providerOptions: { replicate: { num_inference_steps: 4, // 加速生成 output_format: png, }, }, }); fs.writeFileSync(robot.png, image.uint8Array);错误处理方面包内定义了统一的失败响应处理器 replicate-error.ts基于 zod schema 解析响应的detail或error字段优先取detail其次error兜底为Unknown Replicate error与 AI SDK 的错误体系无缝衔接。八、结语纵观 packages/replicate/CHANGELOG.md 的完整变更记录ai-sdk/replicate的演进呈现出三条清晰主线能力扩充图像 → 图像编辑 → Flux-2 多图 → 异步视频编排、类型体系升级ImageModelV2 → V3 → V4ProviderV3 → V4与安全加固同源凭证、响应 URL 校验、空 baseURL 校验。对于正在接入 Replicate 的开发者建议直接使用当前 3.x 版本通过providerOptions.replicate传递模型特有参数利用maxWaitTimeInSeconds控制同步等待并在视频场景优先采用poll/webhook异步流程。若需查阅更多源码级细节可继续阅读 replicate-image-model.ts、replicate-video-model.ts 与对应的 测试文件。【免费下载链接】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），仅供参考
