# Pamba: full documentation > Canonical per-article URLs: https://pamba.app/docs/ (HTML) and https://pamba.app/help/md/ (markdown). # Getting Started ## What is Pamba? > The 2-minute overview: AI avatar videos, real-device posting, and analytics in one loop. Pamba is a platform for growing on TikTok and Instagram with AI-generated UGC videos. You create videos by talking to an agent, and Pamba handles everything downstream: generating the footage with your AI avatar, publishing it from real phones, and tracking how every post performs. ## The loop 1. **Create**: describe an idea or paste a script; the agent writes, generates, and stitches a video fronted by your AI avatar. 2. **Approve**: nothing posts without your sign-off. Review the cut, request changes, or approve. 3. **Publish**: Pamba schedules the post and a real device opens TikTok or Instagram and posts it like a human would. 4. **Learn**: analytics flow back per video and per account: views, likes, comments, watch patterns. 5. **Repeat**: double down on what worked. The agent can plan whole content batches so the loop runs on a cadence. ## What makes it different - **The agent is the interface.** Almost anything you can do by clicking, you can do by asking: "make me three videos about X," "reschedule tomorrow's post," "which video did best last week?" - **Real devices, not APIs.** Posts go out from physical phones, the way a person posts. - **Avatars are yours.** Design a presenter that fits your brand, give them multiple scenes, and reuse them across every video. ## Where to start Follow [Zero to First Post](/help/first-post); it walks the shortest path from an empty workspace to a live TikTok post. ## Zero to First Post: publish your first TikTok video > The hello-world of Pamba: go from an empty account to a video live on TikTok, touching only what you need. This guide takes you from a brand-new account to a video posted on your TikTok, nothing extra, just the shortest path. If you're signed in, the checklist below tracks your real progress and each step deep-links to the right place. ## 1. Create your avatar Your avatar is the AI presenter who appears in your videos. Open **Studio** in the sidebar and click **+ New avatar**: pick a community avatar to start fast, or describe your own (appearance, vibe, niche) and Pamba generates it. You can add scenes (settings your avatar appears in) later; one look is enough for a first post. **Done when:** your workspace has at least one avatar. ## 2. Connect a TikTok account Pamba posts through real devices, so your TikTok account needs to be linked to one. Go to **Studio → Accounts** and follow the connect flow. If your plan includes a managed device, your account gets signed in on one of Pamba's phones; you'll see it listed as ready to post. **Done when:** an account shows as ready for posting. ## 3. Create your first video Hit **Create content** (top right anywhere in Studio, or the shortcuts on Home) and tell Pamba what you want: an idea, a topic, or a full script. Pamba writes the script (or uses yours), generates the avatar footage scene by scene, and stitches the final video. You can watch clips as they finish and swap any take you don't like. **Done when:** a project in your workspace has a finished video. ## 4. Approve and schedule it Videos only publish once you've approved them; that's your quality gate. Review the final cut, approve it, then schedule the post: pick the account, tweak the caption, and choose a time (or let Pamba pick the next good slot). **Done when:** a post is scheduled. ## 5. Watch it go live At the scheduled time, a real phone opens TikTok and publishes your video like a human would. You'll see the post flip to **Posted** on the Schedule page, and analytics start flowing in as views arrive. **Done when:** your first post shows as completed. That's it: you've shipped your first AI-avatar video. ## Where to go next - **Make more videos faster**: ask the agent to generate several concepts at once. - **Understand your numbers**: see the Analytics articles once a few posts are live. - **Grow on autopilot**: set up content batches so Pamba plans, produces, and posts on a cadence. ## Home: your control center > The daily check-in - views this week, your winner, what needs you, and what Pamba is working on. Home is the first page you land on and the only one you need for a daily check-in. It answers three questions: how is my content doing, what needs me, and what is Pamba working on right now? ![Home: views, create shortcuts, the Needs-you queue, and what Pamba is on](/help-shots/home.png) ## Views and your winner The hero shows views over the last 7 days with the change against the prior week, plus recent posted videos. Once a post starts pulling views, the **winner of the week** appears: your best performer, worth studying and repeating. ## Needs you The human queue, most urgent first: posts that failed (with one-click Retry or Dismiss), scripts waiting for your review verdict, and anything else blocked on your judgment. If this list is empty, the machine is running on its own. ## On it What Pamba is doing right now: scripts being written, videos generating, posts queued for today. It's the "don't worry, it's happening" list. ## Create content Shortcuts into the three ways to start a video (from a TikTok link, from an idea, from your script) without leaving Home. ## While you're setting up Until your first video is created, Home shows a setup meter tracking the essentials: brand set up, first video drafted, first video created, account connected. It disappears once you're rolling; the [Zero to First Post](/help/first-post) tutorial follows the same path with more hand-holding. # Creating Videos ## Creating videos with the agent > The chat is the studio: how to go from idea, script, or reference video to a finished cut. The fastest way to make a video in Pamba is to ask for it. The agent can take anything from a vague topic to a finished script and carry it through generation. ## What you can start from - **An idea**: "make a video about why most people quit the gym in February." The agent writes the script, picks a scene, and generates. - **A script**: paste it verbatim; the agent uses your words and just handles production. - **A reference video**: share a TikTok you like and ask Pamba to make your version of it. ## While it generates Videos are generated scene by scene. You can watch clips as they finish, ask for a different take on any clip, or change the script mid-flight. Generation costs credits; the agent tells you the estimated cost before spending when confirmation is on. ## Editing the result Every project has an editor where you can reorder clips, swap takes, trim, and add a text hook overlay. Ask the agent for changes in plain language, or open the editor and do it by hand; both work on the same project. ## Tips - Be specific about tone: "casual, like you're telling a friend" reads differently than "authoritative expert." - One video = one idea. If your script covers three points, consider asking for three videos. - Approve promptly: videos only publish after your approval, so a scheduled slot with an unapproved video will not post. ## The video editor > Reorder clips, swap takes, trim, and add text hooks: by hand or by asking. Every project has an editor showing the video as a timeline of clips. Anything the agent produced, you can adjust. ## What you can do - **Swap takes**: each clip keeps its generation history; pick a different take without regenerating. - **Regenerate a clip**: didn't like any take? Ask for a new one with a tweak ("more energy," "different angle"). - **Reorder and trim**: drag clips around, cut dead air. - **Text hook**: add the overlay text that shows in the first seconds; it's often the difference between a scroll-past and a view. ## Two ways to edit Open the editor and work visually, or tell the agent what to change ("swap the second clip for the previous take, and tighten the intro"). Both operate on the same project, so use whichever is faster for the change at hand. ## Rendering When the cut is right, the final video renders for posting. If you schedule a post while a render is still running, Pamba waits for it within a grace window before posting, so you don't have to babysit the handoff. ## Content batches: plan a week in one sitting > Let Pamba plan, write, and produce content on a cadence instead of one video at a time. One-off videos are how you start; batches are how you grow. A content batch is a planned set of scripts (themed, varied by format, and scheduled across days) that Pamba writes and produces together. ## The flow 1. **Plan**: the agent proposes a batch: topics, formats, and a posting plan grounded in your niche and what's been working. 2. **Review scripts**: approve, edit, or reject each script. Rejected ones don't get produced; feedback teaches the next batch. 3. **Produce**: approved scripts become video projects and generate. 4. **Approve & post**: finished videos go through your normal approval, then post on their planned slots. ## Why batches beat one-offs - Consistency is the algorithm's favorite input: a steady cadence outperforms bursts. - Reviewing ten scripts takes minutes; producing ten videos one prompt at a time takes an evening. - Batches learn: your approvals and edits shape what the next batch proposes. Ask the agent to "plan next week's content" to see your first batch. ## The Studio: your content cockpit > One grid for everything in flight, per avatar and account, plus creating, reviewing, and automating content. The Studio is where your whole content operation lives. Open it from the sidebar and you get one row per avatar and account, one column per day, and a colored chip for every piece of content, so you can see the state of every account at a glance. ![The Studio: the avatar-by-day grid with stage-colored chips](/help-shots/studio-grid.png) ## The Avatars grid Each chip is one piece of content on its day, colored by stage (concept, generating, review, approved, scheduled, posted, failed). Days anchor to yesterday, so you see what just shipped and what's coming. Content that isn't committed to a date yet sits in the Backlog column; suggested placements show as ghost chips until you confirm them. ## Tabs - **Avatars**: the grid above, the default view. - **Accounts**: your account inventory, with views over the last 7 days and an editable daily post cap per account (a hard ceiling on how many videos Pamba posts there per day). - **Content**: where content gets made and reviewed, in four sections: Create, Plans, Drafts, Videos (see below). - **Ideas**: the research feed. Track TikTok accounts you want to learn from, browse their analyzed videos with engagement stats, and turn any of them into scripts or projects. - **Schedule**: calendar and list of every scheduled post. - **Automation**: campaigns that run content on their own (see below). ## The Content section: Create, Plans, Drafts, Videos The Content tab is the production line, with a switcher for its four sections. Drafts and Videos carry unseen-count badges, so you can see at a glance when new work has landed for review since you last looked. ### Create Where every video starts. Three ways in: - **From a video**: paste a TikTok link and Pamba analyzes it and makes your version. - **Write an idea**: describe the topic and the agent writes the script. - **With a script**: paste your own words and they're used verbatim. ![Create content: pick a start, stack cards, create them together](/help-shots/create.png) Stack several cards and submit them together; each becomes its own project and generates independently. ### Plans ![Plans: the planning grid, one row per account, format chips per day](/help-shots/plans.png) The planning grid: what's slotted where for the coming days, per avatar and account, with format chips on each slot. This is the week at a glance; when a campaign drafts a new plan, it lands here first. ### Drafts ![Drafts: the script review desk, approve or cut each one](/help-shots/drafts.png) The script review desk. Every drafted script waits here for your verdict: approve it, edit it, or send it back with feedback. Approving is the moment a script becomes real; it creates the project and starts video generation. Rejected drafts don't get produced, and your feedback teaches the next batch. ### Videos ![Videos: generation triage with stage badges and one-click approve](/help-shots/videos.png) Generation triage: thumbnail cards with stage badges for every video in flight. Finished videos get watched and approved for posting here; stuck or failed generations surface so nothing silently stalls. ## Automation Each campaign runs its accounts on autopilot: turn one on and Pamba plans the week, writes every script, and generates the videos on schedule. A fresh plan is ready for your review by 9am each cycle; you stay the approval gate, and nothing posts without you. Campaigns can be set up any time and turn on with a subscription. # Avatars ## Avatars: your AI presenters > Create custom avatars or start from community ones, and reuse them across every video. An avatar is the AI presenter who fronts your videos: a consistent face, look, and vibe that your audience gets to know. Avatars belong to your workspace, and every video project selects one. ![My Avatars: your roster, with warming, community claims, and creation](/help-shots/avatars.png) ## Two ways to get one - **Community avatars**: ready-made presenters you can adopt instantly. The fastest start; you can always create your own later. - **Custom avatars**: describe the person you want (appearance, age, style, energy) and Pamba generates them. Iterate on the description until the look is right. ## Scenes A scene is a setting your avatar appears in: a desk, a car, a gym, a kitchen. More scenes means more visual variety across videos and even between clips of one video. You can generate new scenes for an avatar at any time; scene generation spends image credits. ## Choosing per video Each project picks its avatar when it's created. Keeping one avatar per account builds recognition; some teams run different avatars for different content series. ## Good to know - Avatars connected to a posting account become that account's "face", and analytics can be filtered by avatar. - If a generated look isn't right, regenerate rather than settling; the avatar is the most-reused asset you'll make. # Publishing & Scheduling ## Scheduling posts > How scheduling works: time slots, device windows, captions, and what the statuses mean. Once a video is approved, you schedule it to an account and Pamba posts it from a real device at the chosen time. ![The posting schedule: scheduled, posted, failed, and cancelled posts per day](/help-shots/schedule.png) ## Scheduling a post From a project (or by asking the agent), pick the account, set the caption, and choose a time, or let Pamba pick the next available slot. Posts publish through physical phones, and each phone has a daily posting window, so slots are real capacity: if a time is taken, Pamba books the nearest free one. ## Post statuses - **Pending**: scheduled, waiting for its time. - **In progress**: a device is posting it right now. - **Posted**: live on the platform; analytics start tracking it. - **Failed**: something stopped it (see [When a post fails](/help/failed-posts)); you can edit, re-approve if needed, and retry. - **Cancelled**: you called it off; the slot was freed. ## Editing a scheduled post Pending posts can be rescheduled, recaptioned, or moved to a different account. Failed posts can be edited too, but their new time is picked automatically when you hit Retry. ## Cross-posting Instagram mirrors can go out alongside TikTok posts, and an Instagram post can share to a linked Facebook account. Mirrors follow their primary post: reschedule the TikTok and the mirrors move with it; retry a failed group and the whole set revives together. ## Connecting TikTok and Instagram accounts > How accounts link to devices, what "ready to post" means, and fixing connection issues. Pamba publishes from physical phones, so posting requires your account to be signed in on a device. This is what makes posts look and behave like a human posted them. ## Connecting Go to **Accounts** and follow the connect flow for TikTok or Instagram. Depending on your plan, your account is signed in on a Pamba-managed device. Once linked, the account shows as ready and appears as a posting target when you schedule. ## What "ready" means Ready = the account is signed in on a device that's online and inside its posting capacity. If an account shows as not ready, posts scheduled to it will fail at their slot rather than silently skipping. ## Instagram + Facebook An Instagram account can share posts to a linked Facebook account (set up through Meta's Accounts Center). Once linked, "share to Facebook" becomes available on Instagram posts. ## Troubleshooting - **Account signed out on the device**: reconnect from the Accounts page; then retry any failed posts. - **Paused accounts**: pausing an account cancels its pending posts and warming activity; resume it to schedule again. - **Wrong account posting**: each scheduled post names its target account explicitly; check the post's account on the Schedule page. ## Account warming > Mature new TikTok accounts before posting: human-like browsing that builds algorithm signal. Fresh TikTok accounts that immediately start posting look like bots. Warming fixes that. Pamba browses TikTok on the account's device like a human would (watching, scrolling, searching your niche) to build an algorithm signal before and between posts. ## How it works - **Session queue**: warming sessions are scheduled automatically and listed with status: pending, in progress, completed, failed. - **Per-avatar config**: set daily minutes, session count, and niche search terms for each avatar's account. - **Session review**: see recent sessions by account, status, and timing. - **Cancel and retry**: stop pending sessions or retry failed ones. ## Safety caps Warming stays within TikTok norms: at most 60 minutes per day across at most 5 sessions per day per account. Posts take priority: a scheduled post can displace a warming session on the same device. # Analytics ## Analytics: reading your numbers > Per-account and per-video performance for TikTok, Instagram, and Facebook, and how to query it in chat. Every post Pamba publishes is tracked: views, likes, comments, and follower movement, per video and per account, across TikTok, Instagram, and Facebook. ## Where to look - **The Analytics page**: trends over time, KPIs, and per-account breakdowns. Filter by account or avatar to compare presenters. - **The agent**: ask directly: "which video did best this week?", "how many views did we get this month?", "compare my two accounts." The agent reads the same data and answers with specifics. ## What the numbers mean - Metrics refresh on a regular cadence (roughly hourly for TikTok, and in 15-minute ticks for Instagram/Facebook), so a just-posted video may take a little while to show its first numbers. - Views on TikTok move fastest in the first hours; judge a video after a day, not a minute. ## Using analytics to grow The point of the loop: find what worked and make more of it. Look for outliers, not averages: one video at 10x your median is a signal about hook, topic, or format. Ask the agent to break down what your top videos have in common and to generate new concepts in that direction. ## Strategy: your living playbook > A playbook tuned to your goals: formats, cadence, and platform mix in one place. The Strategy page is a living playbook tuned to your goals: what to post, how often, and where. - **TLDR table**: at a glance: accounts, avatars, cadence, content types, platforms. - **Goal breakdown**: the campaign objective written out so everyone's aligned. - **Account setup guide**: what goes where, how often, across TikTok, Instagram, and X. - **Recommended formats**: the specific formats that work for your niche: App Demo, Founder-led, Trends, AI Storytelling, and more. - **Posting strategy**: optimal times, frequency guidelines, and pro tips on consistency and batch planning. Pair it with [Analytics](/help/analytics-overview): the playbook says what to try, analytics says what worked, and the next batch leans into the winners. ## Knowledge: what Pamba has learned about your content > The agent's brain, in tiles you can read and edit - patterns, performance rankings, your brief, and playbooks. Knowledge is the agent's brain made visible. Everything Pamba has learned about what works for your accounts lives here, and everything here shapes what the planner and the agent do next. Each tile opens into its own page where you can view and edit. ![Knowledge: the agent's brain as editable tiles](/help-shots/knowledge.png) ## Patterns Formats and creative angles the system has identified, with a lifecycle stage as they rise and fall. Patterns tag your content, and the planner leans on the ones that are working. ## Performance The planner's rankings, built from verified posts over the last 30 days: which formats, patterns, and accounts are actually pulling views. This is what "double down on what works" reads from. ## The brief Your company profile: website, niche, and brand guidance. The agent weaves this into every script it writes, so keeping it sharp is the highest-leverage edit in the product. ## Playbooks Per-account reference playbooks: how a specific account's content should look, sound, and behave. The planner consults the playbook before writing that account's week. ## Formats, Audiences, and Principles Three more tiles round out the brain: **Formats** (the video formats in your rotation, like Yapper or Hook-to-Demo), **Audiences** (who content gets aimed at), and **Principles** (taste rules captured from your feedback, so the same note never has to be given twice). Everything in Knowledge is editable; correcting it is teaching the system. If scripts keep getting something wrong, fix the brief or the playbook once instead of editing every script. # Workspaces & Billing ## Workspaces, members, and invitations > How workspaces organize your accounts and content, and how to invite teammates by email. A workspace holds everything for one brand or client: avatars, video projects, connected accounts, analytics, and billing. You can belong to several workspaces and switch between them. ## Inviting teammates Open workspace settings and invite by email: - **Existing Pamba users** get an email and can accept with one click and land directly in your workspace. - **New users** get an invite link that takes them through account creation and straight into the workspace, skipping the usual onboarding (a short "learn Pamba" tour brings them up to speed instead). Invitations expire after 14 days and can be revoked while pending. Re-inviting someone refreshes their link. ## Roles Members can work with content; admins can also manage settings, members, invitations, and billing. Choose the role when you invite; admins can change it later. ## Multiple workspaces Agencies typically run one workspace per client. Your default workspace is where you land at sign-in; switching is instant, and accounts, analytics, and billing stay cleanly separated. ## Credits and billing > What spends credits, how plans and top-ups work, and where to manage billing. Pamba meters generation with credits. Making things spends them; posting and analytics don't. ## What spends credits - **Video generation**: the main cost; charged per generated clip/scene. - **Image generation**: avatar scenes and starting frames. - Costs are estimated up front in chat when confirmation is on, so nothing spends silently. ## Plans and top-ups Subscriptions include a monthly credit allowance; top-ups add credits any time. Billing is per workspace, managed by workspace admins from settings (checkout and the billing portal are handled by Stripe; the agent can hand you the right links directly). ## Checking your balance Ask the agent ("how many credits do I have left?") or check workspace settings. If a generation would exceed your balance, Pamba tells you before starting rather than failing midway. # Troubleshooting ## When a post fails > Why posts fail, what the error means, and how retry actually works. Posting happens on real phones, and sometimes real-world things get in the way. A failed post is never lost: the video, caption, and account are all still there, waiting for a retry. ## Common failure reasons - **"Project not approved at scheduled time"**: the video reached its slot before you approved it. Approve the project, then hit Retry. - **Device or connection errors**: the phone lost its network or the app misbehaved mid-post. Usually transient; Pamba retries some of these automatically, and a manual Retry re-plans the rest. - **Account not ready**: the account was signed out or paused on its device. Reconnect it, then retry. ## How Retry works Retry finds the next available slot automatically (you don't pick the time) and revives the project's whole failed group: if a TikTok post and its Instagram mirror both failed, retrying either one re-schedules both. The previous error is cleared and the post goes back to **Pending**. ## If it keeps failing Two retries with the same error usually means something needs your attention upstream: the account connection, the video render, or the approval. Ask the agent "why did my post fail?" and it can read the error and point at the fix. Still stuck? Use contact support right from the chat. # Developers ## API & AI agents: drive Pamba programmatically > Workspace-scoped API keys, the public customer API, and ready-made guides for Claude and other agents. Everything the Pamba UI does, an agent can do through the API. The full public API reference lives at [pamba.app/api](/api): endpoint auth, request and response structures, credit usage, and examples. ## Authentication - **Base URL:** `https://api.pamba.app` - **Agent auth:** `X-API-Key` header. Create keys in workspace settings (open the workspace switcher, then Settings). - JWT callers must include `X-Workspace-Id` on workspace-scoped routes; API-key callers don't, since the key already carries the workspace. ## Give your agent the guide Download the guide matching your agent and drop it in its context: - [CLAUDE.md guide](/pamba-claude.md) for Claude agents - [Codex guide](/pamba-codex.md) - [Generic agent guide](/pamba-agent.md) Once your agent has it, a prompt like "What can you do with Pamba?" should produce a concrete menu of workflows, not stale endpoint guesses. ## What your agent can do Track TikTok accounts and mine analyzed videos; add ideas in bulk and remix scripts; create fully automated project batches; generate clips and select takes; schedule, reschedule, cancel, and retry posts; configure warming; create avatars from reference images; manage starting-frame libraries; and pull analytics dashboards and account metrics. ## Credits Generation spends credits (clip generation per model-second, avatar photos and scenes at 15 credits per image, voices at 100, premium voice clones at 1500, hook purchases at 200). Failed operations are never charged, and insufficient-credit requests return `402 Payment Required` with `remaining_credits` and `required_credits`. The live price list is public at `GET /usage/pricing`; use `GET /user` for subscription state and credit totals. ## This help center is agent-readable too Every article here is available as raw markdown: see [/llms.txt](/llms.txt) for the index and [/llms-full.txt](/llms-full.txt) for the whole corpus in one document. # Hidden Gems ## Agent power tips > Things the chat can do that most people never ask for. The agent is the whole product with a text box in front of it. Most users ask for a fraction of what it can do. Some favorites: - **Batch creation**: "make me 5 videos on these 5 topics" kicks off five projects in one message. - **Replicate a winner**: paste a TikTok link and ask for your version of it; Pamba analyzes the original and produces yours. - **Cross-video analytics**: "what do my top 3 videos have in common?" or "compare this month to last month." - **Schedule surgery**: "move everything scheduled Friday to Saturday morning" or "retry all failed posts." - **Website ingestion**: point the agent at your website and it pulls brand context, media, and product info into the workspace profile so scripts sound like you. - **Support without leaving chat**: "contact support: …" files a real support request with the team. If you find yourself doing something click-by-click more than twice, ask the agent to do it. Odds are it can, end to end.