Common Workflows

Short examples for the loops agents usually need: discover state, prepare content, confirm the action, then track the result.

View Markdown

Discover workspace state

CLIbash
reelsfarm agent status
reelsfarm social connected --agent
reelsfarm assets list --category products --agent
reelsfarm posts list --status SCHEDULED --agent
SDKts
const account = await rf.account.get();
const connected = await rf.social.listConnected();
const products = await rf.assets.list("products", { limit: 10 });
const posts = await rf.posts.list({ status: "SCHEDULED", limit: 10 });

Generate an avatar

CLIbash
reelsfarm avatars generate \
  --prompt "Creator selfie style, bright room, holding a phone" \
  --model gpt-image-2.5-sunburst \
  --aspect-ratio 9:16 \
  --quality high \
  --agent

reelsfarm confirm conf_123 --tool reelsfarm_confirm_generate_avatar --agent
SDKts
const preparedOrJob = await rf.avatars.generate({
  prompt: "Creator selfie style, bright room, holding a phone",
  model: "gpt-image-2.5-sunburst",
  aspectRatio: "9:16",
  quality: "high",
});

if ("wait" in preparedOrJob) {
  const result = await preparedOrJob.wait();
}

Avatar model and quality values

Use gpt-image-2.6 for GPT Image 2.6 (the dashboard default) and gpt-image-2.5-sunburst for GPT Image 2.5. Reels Farm routes new images to the generation model and reference edits or conversation continuations to the editing model. GPT Image 2.5 and 2.6 accept low, medium, or high quality; GPT Image 2.6 costs 10 credits at medium and high and 5 at low. Seedream 5.0 Pro accepts basic or high. Use flux-3 for FLUX 3, which accepts basic (1K, about 1 megapixel) or high (about 2 megapixels) for 3 credits, ultra (2K, about 4 megapixels) for 4 credits, or max (4K, about 16 megapixels) for 20 credits. Omit quality for Nano Banana models.

Generate slideshow text

CLIbash
reelsfarm slideshows generate-text \
  --prompt "Summer serum launch for TikTok" \
  --slide-count 6 \
  --agent
SDKts
const slideshowText = await rf.slideshows.generateText({
  prompt: "Summer serum launch for TikTok",
  slideCount: 6,
});
With a Look and a proven formatbash
reelsfarm slideshows generate-text \
  --prompt "Texts with my mom when she finds out how much I spend on iced coffee" \
  --slide-count 4 \
  --design imessage \
  --agent

reelsfarm slideshows generate-text \
  --prompt "The 3 best cold brew makers under $50" \
  --format rated-picks \
  --design classic \
  --agent
  • design is the Look: classic (photo slides with text), tweet, imessage, notebook, magazine, or auto. auto picks a designed Look only when the prompt plainly asks for one.
  • A designed slide comes back with a design object and no text items. Pass it unchanged to create_slideshow or update_slideshow.
  • tweet, notebook, and magazine draw over the slide photo, so those slides still need an imageUrl. An iMessage slide draws no photo, so it needs no imageUrl and no visual context.
  • format is a proven format: help-me-choose (numbered options, viewers vote for a number), numbered-product-last (a list worth saving, with the product as the last item), rated-picks (favourites with honest ratings), or problem-math-steps (a problem, what it really costs, then the steps to fix it). A format sets the slideshow type, and the slide count when slideCount is left out.
  • Use prepare_revise_slideshow_text, or rf.slideshows.reviseText, to change existing text with a plain instruction such as "make slide 2 shorter".

Recreate a TikTok slideshow

Recreate copies a public TikTok photo slideshow for your product. ReelsFarm reads every slide, keeps the format and each slide's text look, writes new text on the same subject, and finds a photo for every slide. The result is a draft slideshow. It takes about two minutes.

CLIbash
reelsfarm slideshows recreate \
  --tiktok-url https://www.tiktok.com/@creator/photo/7550000000000000000 \
  --product-context-id pc_123 \
  --instructions "Use a wedding cake instead of the birthday cake" \
  --wait \
  --agent
SDKts
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",
});
  • Poll reelsfarm_get_recreate_slideshow_job_status. When it completes, slideshowId is the new draft. Open it with reelsfarm_get_slideshow, change it with reelsfarm_update_slideshow, and render it with reelsfarm_prepare_finalize_slideshow.
  • The product is named only where the original names its own product. A product context photo goes on the slides where the original shows its own product.
  • instructions change the text and the photos they apply to, such as a wedding cake instead of a birthday cake. Without instructions, the photos follow the original's.

Find and save slide photos

MCP callsjson
reelsfarm_search_photos
{ "query": "aesthetic iced coffee", "source": "pinterest" }

reelsfarm_save_slide_photos
{ "photos": [{ "url": "https://i.pinimg.com/..." }], "idempotencyKey": "photos-coffee-001" }
  • search_photos searches Pinterest (the default), Tumblr, or Pexels, like the photo picker in the app. Each user can run 30 searches a minute.
  • save_slide_photos saves up to 10 photos per call and returns a ReelsFarm url for each. Use that url as a slide imageUrl.
  • Saved photos do not count toward the upload limit. Photos that no slideshow uses are removed after three days.

Text looks and positions

Slide text can use TikTok's own text styles. Generate the text first, then change these fields on the returned text items before you call create_slideshow or update_slideshow.

Text item fieldsjson
{
  "textFont": "classic",
  "textEffect": "background",
  "textColor": "#ffffff",
  "textX": 0.5,
  "textY": 0.3
}
  • textFont is one of TikTok's 24 text fonts. The tool reference lists the ids.
  • textEffect is none, outline, background, or translucent. textColor is a hex colour: the text colour for none, the outline colour for outline, and the box colour for background and translucent.
  • textFont, textEffect, and textColor win over the older textStyle field.
  • textX and textY place the centre of the text column, from 0 to 1 across and down the slide. When set, they replace textPosition. Items with the same textX and textY stack in one column.
  • One text item per slide is usual. A slide takes up to six.
  • update_slideshow replaces the whole slide list. Send every slide with all its fields: a slide left out is deleted, and a field left out gets its default. Only design keeps its saved value when left out.

Make many slideshows from one format

A saved format holds a content brief, image rules, and publishing defaults, with the same fields as an automation. content.recreateUrl copies a public TikTok photo slideshow: ReelsFarm reads it when the format is saved, and the format takes that slideshow's slide count. A batch makes 1 to 50 slideshows from one format for review. Nothing is posted.

CLIbash
reelsfarm slideshows formats --agent
reelsfarm slideshows batch-create --format-id fmt_123 --count 10 --agent
reelsfarm slideshows batch --batch-id batch_123 --agent
MCP callsjson
reelsfarm_list_slideshow_formats
{}

reelsfarm_prepare_create_slideshow_batch
{ "formatId": "format_uuid", "count": 10, "idempotencyKey": "batch-coffee-001" }

reelsfarm_get_slideshow_batch
{ "batchId": "batch_uuid" }
  • Each slideshow in a batch costs the slideshow generation price, which list_slideshow_formats returns as creditsPerSlideshow. When the format sets images.generatedPhotos, each picture also costs that image model's price.
  • READY batch items have a slideshowId. Retry a failed item with prepare_retry_slideshow_batch_item, or leave one out with exclude_slideshow_batch_item.
  • Create or replace a format with save_slideshow_format, and archive one with archive_slideshow_format.

Describe a product once

CLIbash
reelsfarm product-contexts suggest --url https://example.com/product --agent
reelsfarm product-contexts create \
  --name "Cold brew kit" \
  --description "A one-litre cold brew maker for making coffee at home" \
  --image-url https://example.com/kit.png \
  --agent

A product gives slideshow text, Recreate, and automations the product's name and description. It has up to 6 photos, in order. suggest reads a public product page and suggests the name, the description and the page's photos without saving. Slides that show the product take its photos one by one, unchanged: the first product slide the first photo, the next one the second, and so on.

MCP calls for an appjson
reelsfarm_suggest_product_context_from_url
{ "url": "https://apps.apple.com/us/app/cal-ai-calorie-tracker/id6480417616" }

reelsfarm_create_product_context
{
  "name": "Cal AI - Calorie Tracker",
  "description": "<description from the suggestion>",
  "appStoreUrl": "https://apps.apple.com/us/app/id6480417616"
}

For an App Store link, suggest reads Apple's listing: the exact app name, a description, the app's screenshots as photos, and app with appStoreUrl and iconUrl. Create the product with appStoreUrl: the server keeps the app icon, and when no photos are given it saves up to 6 of the app's screenshots as the photos. Slideshows then show the real app screens on product slides.

Upload product images from an agent

These calls are composable primitives, not a fixed campaign workflow. The create call reserves the shared product-assets quota in request order. In Review mode, confirm it once; completion is an idempotent continuation that must use the same MCP connection and needs no second confirmation.

MCP callsjson
reelsfarm_create_product_upload_sessions
{
  "idempotencyKey": "summer-products-upload-001",
  "files": [
    { "clientId": "front", "filename": "front.webp", "contentType": "image/webp", "size": 481233, "displayName": "Serum front" },
    { "clientId": "detail", "filename": "detail.jpg", "contentType": "image/jpeg", "size": 732190 }
  ]
}

PUT each sessions[].uploadUrl
Use every returned header and the exact declared file bytes.

reelsfarm_complete_product_upload_sessions
{ "sessionIds": ["session_uuid_1", "session_uuid_2"] }

Partial quota fill

The response accepts as many files as fit, in input order, and returns the rest under skipped. Sessions expire after 15 minutes; each file is limited to 100 MB and must be PNG, JPEG, or WebP.

Finalize and export a slideshow video

MCP callsjson
reelsfarm_prepare_finalize_slideshow
{ "slideshowId": "slideshow_uuid", "slides": [/* strict finalized slide objects */], "idempotencyKey": "finalize-summer-001" }

reelsfarm_get_slideshow_export_job_status
{ "jobId": "finalize_job_id" }

reelsfarm_prepare_export_slideshow_video
{ "slideshowId": "slideshow_uuid", "idempotencyKey": "video-summer-001" }

reelsfarm_get_slideshow_video_export_job_status
{ "jobId": "video_export_job_id" }

Video export uses the slideshow-video credit cost. If the finalized slideshow has not changed, the prepare call can return a cached normalized video artifact immediately instead of a new job.

Reuse videos in UGC and schedule the result

MCP callsjson
reelsfarm_list_videos
{ "sourceType": "SLIDESHOW", "limit": 20 }

reelsfarm_prepare_generate_ugc_video
{
  "idempotencyKey": "ugc-summer-001",
  "parts": [
    { "videoUrl": "/api/assets/user-uploads?key=user/hooks/hook.mp4", "sourceType": "my-hooks", "assetCategory": "hooks" },
    { "videoId": "slideshow_video_uuid", "sourceType": "my-videos", "assetCategory": "videos" }
  ],
  "quality": "high"
}

reelsfarm_get_video_job_status
{ "jobId": "ugc_job_id" }

reelsfarm_preflight_publishing
{
  "contentType": "UGC_VIDEO",
  "contentId": "completed_ugc_video_uuid",
  "publishFormat": "VIDEO",
  "connectionIds": ["22222222-2222-4222-8222-222222222222"]
}

reelsfarm_prepare_schedule_post
{
  "contentType": "UGC_VIDEO",
  "contentId": "completed_ugc_video_uuid",
  "scheduledFor": "2026-09-20T15:00:00Z",
  "publishFormat": "VIDEO",
  "platforms": [{ "platform": "TIKTOK", "connectionId": "22222222-2222-4222-8222-222222222222" }],
  "idempotencyKey": "schedule-summer-001"
}

Ordered parts

Part order is composition order, so placing a reusable slideshow video after a hook produces the intended hook-then-slideshow UGC output. A part must provide exactly one of videoId or videoUrl.

Generate a video with a camera move and a look

MCP callsjson
reelsfarm_prepare_generate_video
{
  "prompt": "A woman unboxes a ceramic mug at her kitchen table and smiles",
  "model": "seedance-2.5",
  "aspectRatio": "9:16",
  "durationSeconds": 8,
  "camera": "push_in",
  "look": "phone_ugc",
  "shots": "cuts",
  "idempotencyKey": "mug-unboxing-001"
}

reelsfarm_get_video_generation_status
{ "jobId": "<jobId from the started job>" }
  • These are the Style choices of the Videos box in the app. camera: static, handheld, push_in, pull_back, pan, orbit, follow or drone_rise. look: phone_ugc, studio_product, golden_hour, cinematic, flash_night or vintage_film. Both work on every model. shots: one or cuts.
  • shots cuts makes two or three shots joined by hard cuts in one clip. It needs a Seedance model and 8 seconds or more.
  • look cannot be combined with firstFrameUrl, which already sets the look. None of the three can be combined with motionPreset.
  • Omit a choice to let the prompt rewrite pick it. A choice wins over camera or look words in the prompt.
  • improvePrompt (on by default) rewrites the prompt into the form the model follows best and keeps spoken words as written. The status result returns it as improvedPrompt. With improvePrompt false, the choices still apply as a short sentence before the prompt.
  • Seedance makes 9:16, 16:9, 1:1, 3:4, 4:3 and 21:9; Veo and Omni make 9:16 and 16:9. Check reelsfarm_get_generation_pricing for durations and prices. One video job runs at a time per account.

Generate a product scene

SDKts
const scene = await rf.productScenes.generate({
  avatarUrl: "https://example.com/avatar.png",
  productImageUrl: "https://example.com/product.png",
  prompt: "Natural UGC kitchen counter shot, creator holding the product",
});

Product scene generation starts an asynchronous Product Studio composition. In Review, approve and confirm the prepared action first. In Creator or Autopilot, an allowed prepare call can start the job immediately. Poll the returned job or use the SDK job wrapper.

Schedule content

CLIbash
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 schedule \
  --content-type SLIDESHOW \
  --content-id 11111111-1111-4111-8111-111111111111 \
  --when 2026-10-01T15:00:00Z \
  --publish-format VIDEO \
  --platforms-json '[{"platform":"TIKTOK","connectionId":"22222222-2222-4222-8222-222222222222","tiktokPublishMode":"DIRECT","tiktokPrivacyLevel":"PUBLIC_TO_EVERYONE","tiktokIsAigc":true}]' \
  --caption "Launch day" \
  --agent

reelsfarm confirm conf_123 --tool reelsfarm_confirm_schedule_post --agent
SDKts
const readiness = await rf.posts.preflight({
  contentType: "SLIDESHOW",
  contentId: "11111111-1111-4111-8111-111111111111",
  publishFormat: "VIDEO",
  connectionIds: ["22222222-2222-4222-8222-222222222222"],
});

// Inspect settingsSchema, rules, and limits before choosing platform settings.
if (readiness.targets.some((target) => !target.ready)) {
  throw new Error("Resolve publishing preflight issues first");
}
console.log(readiness.targets.map(({ settingsSchema, rules, limits }) => ({ settingsSchema, rules, limits })));

const prepared = await rf.posts.schedule({
  contentType: "SLIDESHOW",
  contentId: "11111111-1111-4111-8111-111111111111",
  scheduledFor: "2026-10-01T15:00:00Z",
  publishFormat: "VIDEO",
  caption: "Launch day",
  platforms: [{
    platform: "TIKTOK",
    connectionId: "22222222-2222-4222-8222-222222222222",
    tiktokPublishMode: "DIRECT",
    // Use a privacy option returned for this account and an explicit AI disclosure.
    tiktokPrivacyLevel: "PUBLIC_TO_EVERYONE",
    tiktokIsAigc: true,
  }],
});

Account-specific publishing settings

Publishing preflight returns settingsSchema, rules, and limits for each target. settingsSchema is JSON Schema 2020-12 for one platforms entry. Use its exact connectionId and platform. ready checks account and media readiness; required settings still need values. TikTok options reflect live account restrictions. Integration targets can expose fewer settings than native accounts. Missing limits are unknown. Repeat preflight when content, format, or destination changes.

For a native Instagram Reel, instagramShareToFeed defaults to false. False keeps the Reel in the Reels tab only. True also allows it on the profile grid. Send this setting only when the selected account's video settingsSchema includes it. It is not available for Instagram integration accounts or photo posts. Trial Reel and profile grid are separate settings.

Native Instagram video targetjson
{ "platform": "INSTAGRAM", "connectionId": "22222222-2222-4222-8222-222222222222", "instagramTestReel": false, "instagramShareToFeed": false }

Create an automation

CLIbash
reelsfarm automations create \
  --json-definition '{"name":"Daily TikTok","status":"PAUSED","targetConnectionId":"22222222-2222-4222-8222-222222222222","schedule":{"slots":[{"days":["mon"],"timeLocal":"09:00"}]},"content":{"topic":"mindset","slidesCount":5}}' \
  --agent

In Review, automation creation returns a prepared action. Autopilot can execute authorized automation work immediately. Creator blocks automation activation. Keep new automations paused until the content rules, account target, and schedule are settled.

With a format, a Look, text looks, and photo sourcesjson
{
  "name": "Coffee picks",
  "status": "PAUSED",
  "targetConnectionId": "22222222-2222-4222-8222-222222222222",
  "timezone": "Europe/Berlin",
  "schedule": { "slots": [{ "days": ["mon", "wed", "fri"], "timeLocal": "17:30" }] },
  "content": {
    "topic": "home coffee",
    "slidesCount": 5,
    "slidesCountMax": 7,
    "provenFormat": "rated-picks",
    "design": "classic",
    "textLooks": [{ "textFont": "classic", "textEffect": "background", "textColor": "#ffffff" }]
  },
  "images": {
    "photoSources": { "pinterest": true, "tumblr": false, "pexels": false, "collections": false },
    "generatedPhotos": { "count": 1, "fromSlide": 1, "toSlide": 1 }
  },
  "publishRules": {
    "caption": "[Which one would you pick?] [Save this for your next order]",
    "tiktokSettings": { "tiktokTitle": "Coffee gear I would buy again" }
  }
}
  • slidesCount with slidesCountMax gives each post a random number of slides in that range.
  • provenFormat and design work as in slideshow text generation. textLooks lists up to six TikTok text looks, and each post uses one of them. Leave it out to let the AI pick a look per post.
  • recreateUrl copies the format of a public TikTok photo slideshow on every run, with new words and new photos. narrativeContent then says what to change.
  • photoSources searches Pinterest, Tumblr, or Pexels for every slide. collections adds the image collections in collectionIds. generatedPhotos makes pictures with an image model on the chosen slides; each costs that model's credits.
  • To rotate captions across runs, put each caption in square brackets.
  • An ACTIVE automation needs a TikTok photo title (tiktokSettings.tiktokTitle, 1 to 90 characters) and photos for every slide: a photo source, an image collection, or fixed images. iMessage posts need no photos.

Track the result

CLIbash
reelsfarm posts status --id post_123 --agent
reelsfarm events recent --limit 20 --agent
SDKts
const status = await rf.posts.getStatus("post_123");
const events = await rf.events.recent({ limit: 20 });