ReelsFarm

@reelsfarm/mcp-client

适用于 ReelsFarm MCP 服务的强类型 TypeScript SDK 和 CLI。

版本 3.9

SDK 3.9.2 与 ReelsFarm MCP 服务 3.9.2 和契约 2026-10-26.1 相匹配。它涵盖全部 177 个公开工具。变更和生成结果 包含明确的 ReelsFarm 来源信息、执行状态和 assetCreated 完成信号。

版本 3.9 会使用各自专属的确认工具来确认每项已准备的操作， 因为自 3.7 起，服务不再接受客户端调用 reelsfarm_confirm_action。 从 3.6 升级：其中的确认操作在当前服务上会失败，且 validateToolSurface: 'throw' 会拒绝连接。请阅读 MIGRATION.md。

此外，它还新增了幻灯片 Looks（推文、iMessage、笔记本、杂志封面）、 精选格式、通过 TikTok 链接进行 Recreate、支持自由文本位置的 TikTok 文本字体和模式、 照片搜索、已保存格式和批次、自动化照片来源和 AI 图片、Hook 反应风格，以及 Videos 的自然语音。

MCP 2.x 的发布别名已移除。更新发布集成之前，请阅读 MIGRATION.md。

npm install @reelsfarm/mcp-client

import { ReelsFarmClient, ReelsFarmJob } from '@reelsfarm/mcp-client';

const rf = new ReelsFarmClient({
  apiKey: process.env.REELSFARM_API_KEY,
  validateToolSurface: 'throw',
});

await rf.ready();

const avatar = await rf.avatars.generate({
  prompt: '30 多岁女性，休闲装，智能手机自拍风格',
  model: 'gpt-image-2.5-sunburst',
  aspectRatio: '9:16',
  quality: 'high',
});

if ('confirmationId' in avatar) {
  console.log('审核模式需要确认：', avatar);
} else if (avatar instanceof ReelsFarmJob) {
  const result = await avatar.wait();
}

审核模式默认返回 PreparedAction。其 confirmationTool 指明用于确认它的唯一工具， 例如 reelsfarm_confirm_generate_avatar；用户批准后，使用 confirmationId 调用该工具。 受信任的应用可以设置 autoConfirm: true，自动确认审核操作。Creator 和 Autopilot 连接会根据服务端管理的连接策略执行已启用的功能，无需额外的 SDK 审批步骤。

Nano Banana 2.1 请使用 nano-banana-2-1。旧版 nano-banana-2-pro 键 同样使用 2.1。公开的 GPT Image 2.5 模型键请使用 gpt-image-2.5-sunburst。 GPT Image 2 和 GPT Image 2.5 支持 low、medium 或 high 画质。 Seedream 5.0 Pro 支持 basic 或 high。Nano Banana 模型请省略 quality。

作业等待与发布预检

所有 13 个生成、导入和导出状态方法都接受 { waitMs: 25000 }。 使用 0 到 25000 之间的整数。省略此参数或设为 0，即可立即获取快照。 当记录的进度发生变化、作业结束或等待时间用尽时，服务端会返回。 此选项不适用于操作或发布状态工具。

const snapshot = await rf.avatars.getJobStatus(jobId, { waitMs: 25000 });
// A ReelsFarmJob also supports job.getStatus({ waitMs: 25000 }).
console.log(snapshot.jobProgress);

jobProgress 包含 step、terminal、nextPollAfterMs 和可用的批次数量。 即使批次已完成，也要检查各项结果；部分项目可能会失败。 SDK 在解包作业结果时会保留这些字段。job.wait() 会遵循服务端建议的轮询间隔，并对较旧的响应采用退避策略。

发布预检目标包含 settingsSchema（针对一个 platforms 条目的 JSON Schema 2020-12）、rules 和 limits。根据确切的账号和媒体结果构建设置。ready 会检查账号和媒体是否就绪；必填设置仍需提供值。缺少的限制信息视为未知。集成目标公开的设置可能少于原生连接。更改内容、格式或账号后，请再次运行预检。

对于原生 Instagram 视频，将 instagramShareToFeed: false 设为仅在 Reels 标签页中显示 Reel。将其设为 true，则也允许 Reel 显示在个人主页网格中。新创建的原生 Reel 默认值为 false。Instagram 集成账号或照片帖子不支持此字段。发送此字段前，请确认所选账号的 settingsSchema 中包含它。instagramTestReel 是单独的设置。

当 ReelsFarm 通过其托管集成为 Instagram 或 Facebook 账号建立连接时，已连接账号和社交账号列表会将该账号标记为 managed: true。像发布到其他集成账号一样，向其发布内容。

对话式生成

头像和产品场景作业会返回 conversationId、parentGenerationId 和 jobId。将对话和父级 ID 传入下一次生成，即可继续同一分支。通过 rf.imageGenerations.getConversation(conversationId) 读取完整分支。

const nextAvatar = await rf.avatars.generate({
  prompt: 'Keep the same person and use a tighter crop',
  sourceImageUrl: previousImageUrl,
  conversationId,
  parentGenerationId: previousJobId,
});

Hook 生成接受 customPrompt、所有当前的 Veo 和 Seedance 模型、时长，以及可选的口播脚本设置。幻灯片生成接受 Max 模式的视觉上下文。使用 rf.slideshows.reviseText(...)，可将自然语言指令应用于当前完整的幻灯片文本状态。

幻灯片文本生成和修订接受控制面板中的 effort 预设： light、low、medium、high 和 extra_high。更高的强度会使用更多视觉参考（0、2、5、10 或 20 个），并占用更多模型时间。extra_high 还会检查渲染后的文本布局，是控制面板的默认设置。不使用 effort 时，Max 模式最多接受 5 个视觉参考；使用时最多接受 20 个。请为每个参考提供对应幻灯片的 aspectRatio，因为缺少该值时，布局检查会假定比例为 1:1。

const textJob = await rf.slideshows.generateText({
  prompt: '8 slides about cold brew at home',
  slideCount: 8,
  maxMode: true,
  effort: 'high',
  visualContext: slideImages.map((imageUrl, order) => ({ order, imageUrl, aspectRatio: '9:16' })),
});

外观、格式与重制

generateText 接受一种外观和一种经过验证的格式。设计好的幻灯片会返回一个 design 对象，且不包含文本项；请原样传递给 create 或 update。 iMessage 幻灯片不会绘制照片，因此不需要 imageUrl 或视觉上下文。 只有当提示词要求使用设计外观时，auto 才会选择设计外观。

const chat = await rf.slideshows.generateText({
  prompt: 'Texts with my mom when she finds out how much I spend on iced coffee',
  slideCount: 4,
  design: 'imessage',
});

const picks = await rf.slideshows.generateText({
  prompt: 'The 3 best cold brew makers under $50',
  format: 'rated-picks',
  design: 'classic',
});

rf.slideshows.recreate(...) 会为你的产品复制公开的 TikTok 照片幻灯片：格式和文本外观保持一致，文字内容换新，并为每张幻灯片配上一张照片。 大约需要两分钟，完成后，状态中会包含 slideshowId。

const job = await rf.slideshows.recreate({
  tiktokUrl: 'https://www.tiktok.com/@creator/photo/7550000000000000000',
  productContextId,
  instructions: 'Use a wedding cake instead of the birthday cake',
});

文本项接受 TikTok 的 textFont、textEffect（none、outline、background、translucent）和 textColor，这些设置优先于 textStyle；还接受用于自由定位的 textX 和 textY（0 到 1）。 searchPhotos(...) 可在 Pinterest、Tumblr 或 Pexels 上查找照片，而 savePhotos(...) 会将选中的照片转换为幻灯片可使用的 ReelsFarm URL。 saveFormat(...) 和 createBatch(formatId, count) 可根据一种格式创建多份幻灯片，就像应用现在的“制作 10 份”功能一样。

视频工作台

rf.videos.generateVideo(...) 会启动与仪表板“视频”工作台相同的任务。它支持文本生成视频、带可选结束帧的起始帧，或最多三张参考图片。 Seedance 模型还接受一个参考视频和一个参考音频文件。请勿将帧与参考媒体组合使用。 帧和参考媒体请使用自有的 ReelsFarm 资源 URL。起始帧为人物时，motionPreset 会让视频以 shocked 或 grateful 等吸睛反应开场。 带音频时，naturalSpeech（默认开启）会让引号中的口播听起来像真人，同时不改变文字；将其设为 false，即可按原样发送提示词。

const video = await rf.videos.generateVideo({
  prompt: 'Slow push-in on a latte on a sunny cafe table',
  model: 'seedance-2.5',
  durationSeconds: 8,
  aspectRatio: '9:16',
  category: 'product',
});

if (video instanceof ReelsFarmJob) {
  const status = await video.wait();
  console.log(status.video?.id); // Publish it with contentType UGC_VIDEO.
}

模型包括 seedance-2.5（默认）、seedance-2、seedance-2-fast、veo-3.1、veo-3.1-fast 和 gemini-omni-1.1-flash。每个模型支持的时长、宽高比和分辨率各不相同。 rf.account.getGenerationPricing() 会在 videoGeneration 下列出各模型及其每秒价格。 使用 rf.videos.getGenerationStatus(jobId, { waitMs: 25000 }) 轮询。任务完成后，会在 video 中返回已完成的视频库视频。

每个账户一次只能运行一个视频任务，涵盖 hooks、AI Clone 和“视频”工作台。其他请求会失败，并返回错误代码 VIDEO_JOB_IN_PROGRESS 以及当前活动任务的名称。请等待该任务完成，然后使用新的幂等键重试。 若要创建由虚拟形象主导的 hook 短片，请使用 rf.hooks.generate(...)。

图像模板

rf.imageGenerations.listTemplates({ category }) 会返回仪表板「图像」工作台中的产品和信息图模板。每个模板都包含一张参考图像、带有 [PLACEHOLDER] 字段的提示词概要，以及要调用的生成工具。替换占位符，删除无法填写的行，并以模板的 categoryLine 开始提示词。

const { templates } = await rf.imageGenerations.listTemplates({ category: 'infographics' });
const [template] = templates;
if (template && !template.requiresProduct) {
  await rf.avatars.generate({
    mode: 'reference',
    sourceImageUrl: template.referenceUrl,
    prompt: `${template.categoryLine}\n${filledBrief}`,
    model: template.model,
    aspectRatio: template.aspectRatio,
    quality: template.quality,
  });
}

对于 requiresProduct: true 的模板，请调用 rf.productScenes.generate(...)，将 sourceImageUrl 设为 referenceUrl，并将 productImageUrl 设为产品照片。peopleTemplate 提供了 rf.avatars.listTemplates() 返回的人物参考图像的概要和设置。

SDK 也直接映射了网页内容库工作流：

const gallery = await rf.mediaCollections.listGallery({ kinds: ['COLLECTION', 'AVATAR'] });
const collections = await rf.mediaCollections.list();
const communityImages = await rf.community.listImages(collectionId, { random: true });
const voices = await rf.aiClones.listVoices({ search: 'warm' });
const importJob = await rf.hooks.importClips({
  items: [{ url: youtubeUrl, start: "0", length: "5" }],
});
const infographics = await rf.mediaCollections.listGallery({
  kinds: ['AVATAR', 'PRODUCT_PLACEMENT'],
  imageCategory: 'infographics',
  groupCollections: true,
});
const firstItems = await rf.mediaCollections.getItems(collectionId, 'all', { limit: 50 });
const { totalCount } = await rf.videos.list({ category: 'people' });

imageCategory 只筛选生成的图像，因此请将 kinds 设为仅返回图像。groupCollections: true 会将每个合集作为一个条目返回，与仪表板图库标签页的行为一致。合集条目会在一次响应中返回，除非你设置了 limit 或 cursor；此时请继续获取，直到 hasMore 为 false。视频列表会返回 totalCount，而第一页资源也会返回类别的 totalCount。请使用这些总数，而不要对单页内容计数。

相同的 MCP 契约现已涵盖统一图库、个人媒体合集、社区图像、Hook 导入状态与任务、AI Clone 语音搜索、产品上下文 URL 建议、已保存角色身份提取，以及全部 8 种创意回收站项目类型：头像、产品植入、视频、幻灯片、已存储资源、已保存角色、草稿和产品上下文。恢复项目时，请使用 rf.trash.list() 返回的确切类型和 ID。永久删除仍只能在仪表板中进行。

协议与 OAuth

SDK 使用稳定版 MCP TypeScript SDK v2。它会探测 2026-07-28 协议，并在需要时回退到旧版 2025 握手。

OAuth 客户端应仅请求所需的功能。为保持兼容，默认值仍为 mcp:full：

const rf = new ReelsFarmClient({
  oauth: {
    redirectUri: 'http://127.0.0.1:3456/callback',
    scopes: ['content:read', 'content:generate'],
    onAuthorizationUrl: openInBrowser,
  },
});

await rf.raw.listTools();
await rf.completeOAuthCallback(callbackUrl);

请将完整的回调 URL 传给 completeOAuthCallback。SDK 会在兑换授权码之前验证重定向 URL、OAuth 状态和授权服务器颁发者。SDK 不会公开原始授权码完成方法，因为这种形式本身无法验证状态。

CLI

npm install -g @reelsfarm/mcp-client
reelsfarm login --api-key rfmcp_xxx
reelsfarm whoami
reelsfarm avatars list
reelsfarm avatars generate --prompt "Creator selfie style" --model gpt-image-2.5-sunburst --aspect-ratio 9:16 --quality high --wait
reelsfarm image-generations templates --category product
reelsfarm account pricing
reelsfarm videos generate --prompt "Slow push-in on a latte" --model seedance-2.5 --duration 8 --aspect-ratio 9:16 --wait
reelsfarm videos list --category product
reelsfarm media-collections gallery --kinds COLLECTION,AVATAR
reelsfarm ai-clones voices --search warm
reelsfarm hooks import-capabilities
reelsfarm posts preflight --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --publish-format VIDEO --connection-ids 22222222-2222-4222-8222-222222222222 --agent
reelsfarm posts list --json

凭据按以下顺序解析：构造函数选项、环境变量，然后是 CLI 配置文件 ~/.reelsfarm/config.json。设置 REELSFARM_CONFIG_DIR 可使用其他配置目录。

将 ReelsFarm 与 AI Agent 搭配使用

ReelsFarm 可供具备 shell 能力的 Agent 安全使用，但必须以 Agent 模式调用：

reelsfarm agent status
reelsfarm agent commands
reelsfarm social connected --agent
reelsfarm posts schedule --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --when 2026-09-01T15:00:00Z --platforms tiktok:22222222-2222-4222-8222-222222222222 --publish-format VIDEO --agent
reelsfarm confirm conf_123 --tool reelsfarm_confirm_schedule_post --agent

使用 --agent 或设置 REELSFARM_AGENT_MODE=1，即可在 stdout 上接收严格的 JSON 封装。Agent 模式绝不会在命令输出中混入表格或面向用户的说明。错误也会以 JSON 格式输出到 stdout，并返回非零退出代码。

生成、排期、发布、更新和删除等预备操作在 Review 模式下会返回确认载荷。Creator 和 Autopilot 可以立即执行允许的操作；Agent 模式仅控制输出格式。返回确认信息时，请先查看摘要，再运行其提供的 nextStep：reelsfarm confirm <confirmationId> --tool <confirmationTool> --agent。仅当应用应自动确认 Review 模式下的操作时，才传入 --yes。 --dry-run 会发送给服务端；在 Review、Creator 或 Autopilot 模式下均不会产生修改，即使同时使用 --yes 也一样。

服务端连接策略对直接写入具有最终决定权。Creator 可以创建和编辑内容，但不能发布内容或启用自动化。Autopilot 可以发布内容并管理自动化，但须遵守账户限制。凭据、连接模式、Webhook 安全和永久删除操作仅可在控制面板中进行，本软件包不提供这些功能。

幂等性与操作恢复

对于每次逻辑变更，SDK 都会生成一个 UUID；如果传输响应不明确，则会重复使用该 UUID。如果重试操作还必须在进程重启后有效，请在变更输入中提供 idempotencyKey，或在 CLI 中使用 --idempotency-key <key>。切勿将同一个键用于不同参数。

SDK 不会在确认后自动重新准备操作。传输失败且结果不明确时，SDK 会安全地重放同一请求一次；如果服务端返回了持久化操作，则会轮询该操作：

reelsfarm operations get --id op_123 --agent
reelsfarm operations wait --id op_123 --timeout 30000 --agent

结构化错误会区分身份验证、权限范围不足、策略拒绝、速率限制、幂等性冲突、操作进行中和计划限制。自动化请求被拒绝时，会返回代码为 INVALID_AUTOMATION 的 ReelsFarmValidationError。活动视频任务冲突会返回代码为 VIDEO_JOB_IN_PROGRESS 的可重试 ReelsFarmToolError。OAuth 配置文件会将轮换刷新令牌保存在现有的受保护配置文件令牌存储中，直至令牌被撤销或安全事件要求重新授权。

端点

默认的 MCP 端点为 https://mcp.reelsfarm.com/mcp。使用 SDK 时传入 serverUrl，或使用 CLI 时传入 --server-url，即可指定其他部署。默认情况下，SDK 会拒绝非回环地址上的明文 HTTP。只有在受信任的私有开发端点上，才设置 allowInsecureHttp: true 或 REELSFARM_ALLOW_INSECURE_HTTP=1。CLI 也接受 --allow-insecure-http。

开发

npm install
npm run typecheck
npm test
npm run check:manifest
npm run build

仓库中已提交的工具清单反映了当前可发现的 ReelsFarm MCP 接口。仅限控制面板使用的凭据、webhook 和永久删除工具不会纳入公开 SDK 目录。当两个仓库相邻时，清单检查会将 177 个公开 SDK 工具与应用生成的公开工具参考，以及发布版本和契约版本与应用 MCP 服务进行比对。当服务新增或移除工具时，请使用 npm run generate:tools，并连接经过身份验证的 MCP 端点。

发布前检查和平台设置

在调用排期或发布操作前，请先运行发布前检查。服务会在创建或执行操作前再次进行检查。

const readiness = await rf.posts.preflight({
  contentType: 'SLIDESHOW',
  contentId: slideshowId,
  publishFormat: 'VIDEO',
  connectionIds: [tiktokConnectionId, youtubeConnectionId],
});

const scheduled = await rf.posts.schedule({
  contentType: 'SLIDESHOW',
  contentId: slideshowId,
  publishFormat: 'VIDEO',
  scheduledFor: '2026-09-01T15:00:00.000Z',
  platforms: [{
    platform: 'TIKTOK',
    connectionId: tiktokConnectionId,
    captionOverride: 'TikTok caption',
    tiktokPublishMode: 'DIRECT',
    tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
    tiktokAllowComment: true,
    tiktokCommercialContentEnabled: false,
  }, {
    platform: 'YOUTUBE',
    connectionId: youtubeConnectionId,
    youtubeTitle: 'Launch Short',
    youtubePrivacyStatus: 'UNLISTED',
    youtubeMadeForKids: false,
    youtubeContainsSyntheticMedia: true,
  }],
});

CLI 接受简单的 platform:connectionId 键值对。需要设置说明文字或平台设置时，请使用 --platforms-json。

发布前，可使用 rf.posts.update(...) 编辑帖子。使用 platform 和 connectionId 为每个现有目标命名（在 rf.posts.list(...) 中对应 accountId）；未提供的字段会保留已保存的值，媒体和账号无法更改。将 TikTok 切换为 DIRECT 时，需要提供 tiktokPrivacyLevel，视频还需要提供 tiktokIsAigc。帖子开始发布后，将无法编辑。

await rf.posts.update(scheduledPostId, {
  caption: 'New caption',
  platforms: [{
    platform: 'TIKTOK',
    connectionId: tiktokConnectionId,
    tiktokPublishMode: 'DIRECT',
    tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
    tiktokIsAigc: true,
  }],
});

在 CLI 中，使用 reelsfarm posts update --id <id> --platforms-json <json>。

自动化

自动化 tiktokSettings 接受与 TikTok 发布目标相同的设置，包括 tiktokPublishMode、tiktokPrivacyLevel、tiktokTitle、互动和披露标记以及封面设置。tiktokPostMode 仍是旧版别名；tiktokPublishMode 和 tiktokPrivacyLevel 的优先级高于它。

ACTIVE 自动化的 tiktokTitle 必须为 1 到 90 个字符，并且每张幻灯片都必须至少有一个图片集合或一张固定图片。商业内容需要设置 tiktokBrandOrganic、tiktokBrandedContent，或同时设置两者；品牌内容不能使用 SELF_ONLY 隐私级别。服务会在审批前检查每个请求。

若要在不同运行中轮换说明文字，请将每条说明文字放在方括号中，例如 [First caption][Second caption]。rf.automations.update(...) 会保留省略的顶层字段、替换 images，并逐字段合并 publishRules。新的 caption 会替换已保存的 TikTok captionOverride。

await rf.automations.update(automationId, {
  status: 'ACTIVE',
  publishRules: {
    caption: '[Morning tip][Evening tip]',
    tiktokSettings: {
      tiktokPublishMode: 'DIRECT',
      tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
      tiktokTitle: 'Daily skincare tip',
    },
  },
});