ReelsFarm

@reelsfarm/mcp-client

Typed TypeScript SDK and CLI for the ReelsFarm MCP server.

Version 3.11

SDK 3.11.0 matches ReelsFarm MCP server 3.11.0 and contract 2026-10-30.1. It tracks all 177 public tools. Mutation and generation results include explicit ReelsFarm provenance, execution state, and an assetCreated completion signal.

Server 3.11 lists the same tools in about a quarter of the old size. Confirmation tools take only confirmationId, so a dry-run client no longer calls them. Read MIGRATION.md for the other changes.

Version 3.9 confirms each prepared action with its own confirmation tool, because servers since 3.7 no longer accept reelsfarm_confirm_action from clients. Update from 3.6: its confirmations fail against the current server, and validateToolSurface: 'throw' refuses to connect. Read MIGRATION.md.

It also adds slideshow Looks (tweet, iMessage, notebook, magazine cover), proven formats, Recreate from a TikTok link, TikTok text fonts and modes with free text positions, photo search, saved formats and batches, the automation photo sources and AI pictures, hook reaction styles, and natural speech for Videos.

Publishing aliases from MCP 2.x are removed. Read MIGRATION.md before you update a publishing integration.

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: 'Woman in her 30s, casual outfit, smartphone selfie style', model: 'gpt-image-2.5-sunburst', aspectRatio: '9:16', quality: 'high', });

if ('confirmationId' in avatar) { console.log('Review mode requires confirmation:', avatar); } else if (avatar instanceof ReelsFarmJob) { const result = await avatar.wait(); }

Review mode returns a PreparedAction by default. Its confirmationTool names the one tool that confirms it, such as reelsfarm_confirm_generate_avatar; call it with the confirmationId after the user approves. Trusted applications can set autoConfirm: true to confirm Review actions automatically. Creator and Autopilot connections execute the capabilities enabled by their server-owned connection policy without an extra SDK approval step.

Use nano-banana-2-1 for Nano Banana 2.1. The legacy nano-banana-2-pro key also uses 2.1. Use gpt-image-2.5-sunburst as the public GPT Image 2.5 model key. GPT Image 2 and GPT Image 2.5 accept low, medium, or high quality. Seedream 5.0 Pro accepts basic or high. FLUX 3 (flux-3) accepts basic (1K), high (about 2 megapixels), ultra (2K), or max (4K); bigger sizes cost more credits, and the prepared result's estimate follows the size. Omit quality for Nano Banana models.

Job waits and publishing discovery

All 13 generation, import, and export status methods accept { waitMs: 25000 }. Use an integer from 0 through 25000. Omit it or use 0 for an immediate snapshot. The server returns when recorded progress changes, the job ends, or the wait budget expires. This option does not apply to operation or publish status tools.

const snapshot = await rf.avatars.getJobStatus(jobId, { waitMs: 25000 });

// A ReelsFarmJob also supports job.getStatus({ waitMs: 25000 }). console.log(snapshot.jobProgress);

jobProgress contains step, terminal, nextPollAfterMs, and available batch counts. Inspect item results even when a batch completes; some items can fail. The SDK preserves these fields when unwrapping job results. job.wait() follows the server's suggested polling delay, with backoff for older responses.

Publishing preflight targets include settingsSchema (JSON Schema 2020-12 for one platforms entry), rules, and limits. Build settings from the exact account and media result. ready checks account and media readiness; required settings still need values. Missing limits are unknown. Integration targets can expose fewer settings than native connections. Run preflight again after changing the content, format, or account.

For a native Instagram video, set instagramShareToFeed: false to keep the Reel in the Reels tab only. Set it to true to also allow it on the profile grid. New native Reels default to false. This field is not available for Instagram integration accounts or photo posts. Check that the selected account's settingsSchema includes it before sending it. instagramTestReel is a separate setting.

Connected and social account lists mark an account managed: true when ReelsFarm connected the Instagram or Facebook account through its managed integration. Publish to it like any other integration account.

Conversational generation

Avatar and product-scene jobs return conversationId, parentGenerationId, and jobId. Pass the conversation and parent IDs into the next generation to continue the same branch. Read the complete branch through 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 generation accepts customPrompt, all current Veo and Seedance models, duration, and optional spoken script settings. Slideshow generation accepts Max mode visual context. Use rf.slideshows.reviseText(...) to apply a natural language instruction to the complete current slide text state.

Slideshow text generation and revision accept the dashboard effort presets: light, low, medium, high, and extra_high. Higher effort uses more visual references (0, 2, 5, 10, or 20) and more model time. extra_high also reviews the rendered text layout and is the dashboard default. Without effort, Max mode accepts up to five visual references; with it, up to 20. Give each reference its slide aspectRatio, because layout checks assume 1:1 when it is missing.

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' })), });

Looks, formats, and Recreate

generateText takes a Look and a proven format. A designed slide comes back with a design object and no text items; pass it unchanged to create or update. An iMessage slide draws no photo, so it needs no imageUrl and no visual context. auto picks a designed look only when the prompt asks for one.

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(...) copies a public TikTok photo slideshow for your product: the same format and text looks, new words, and a photo for every slide. It takes about two minutes, and the finished status has the 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', });

Text items accept TikTok's textFont, textEffect (none, outline, background, translucent) and textColor, which win over textStyle, plus textX and textY (0 to 1) for a free position. searchPhotos(...) finds photos on Pinterest, Tumblr, or Pexels, and savePhotos(...) turns picks into ReelsFarm URLs a slide can use. saveFormat(...) and createBatch(formatId, count) make many slideshows from one format, as Make 10 now does in the app.

Videos workbench

rf.videos.generateVideo(...) starts the same job as the dashboard Videos workbench. It supports text-to-video, a start frame with an optional end frame, or up to three reference images. Seedance models also accept one reference video and one reference audio file. Do not combine frames with reference media. Use owned ReelsFarm asset URLs for frames and references. With a start frame of a person, motionPreset opens the video with a hook reaction such as shocked or grateful. With audio, naturalSpeech (on by default) makes spoken lines in quotes sound like a real person without changing the words; set it to false to send the prompt exactly as written.

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. }

The models are seedance-2.5 (the default), seedance-2, seedance-2-fast, veo-3.1, veo-3.1-fast, and gemini-omni-1.1-flash. Each model supports its own durations, aspect ratios, and resolutions. rf.account.getGenerationPricing() lists them with per-second prices under videoGeneration. Poll with rf.videos.getGenerationStatus(jobId, { waitMs: 25000 }). A completed job returns the finished library video in video.

One video job runs at a time per account, across hooks, AI Clone, and the Videos workbench. Another request fails with code VIDEO_JOB_IN_PROGRESS and names the active job. Wait for that job to finish, then retry with a new idempotency key. For an avatar-led hook clip, use rf.hooks.generate(...).

Image templates

rf.imageGenerations.listTemplates({ category }) returns the Product and Infographics templates from the dashboard Images workbench. Each template has a reference image, a prompt brief with [PLACEHOLDER] fields, and the generation tool to call. Replace the placeholders, remove lines you cannot fill, and start the prompt with the template 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, }); }

For a template with requiresProduct: true, call rf.productScenes.generate(...) with sourceImageUrl set to referenceUrl and productImageUrl set to the product photo. peopleTemplate gives the brief and settings for the people reference images from rf.avatars.listTemplates().

The SDK also maps the web content library workflows directly:

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