MCP workflows

Start with get_workspace and get_studio_options. Look up real account, influencer, product, and media IDs in the chosen workspace before calling a write tool. Examples use fictional UUIDs and keys; replace them with returned IDs and a key for your intended action. These examples describe contracts, not verified live generations or publications.

Create a post

1. Read get_brand, list_products, list_influencers, and relevant list_media results.
2. Read get_studio_options. To use a built-in template, call get_template with its returned slug, then use its fields and settings. list_templates lists saved templates, favorites, and previews.
3. Estimate with estimate_content_cost, then send the same generation settings to create_content with a fresh key.

{
  "format": "slideshow",
  "mode": "content",
  "prompt": "Three ways to keep a desk tidy",
  "imageSource": "fresh",
  "idempotency_key": "tidy-desk-post-1"
}

1. Use the returned jobId in get_job as job_id. A completed job's result.contentItemId or result.contentItemIds identifies posts; result.mediaAssetIds identifies standalone media. Follow the returned nextAction.
2. Read get_content for each post. Show it to the customer before deciding whether to edit or publish.

mode defaults to content; imageSource defaults to fresh. manual uses selected mediaIds; auto selects library media. Product or prompt references can force fresh generation even when manual is selected. Do not assume library settings make a referenced request free.

Content mode normally needs a nonblank prompt. Green-screen posts can use their selected meme clip as the brief, and prepared remixes carry their source structure. Selected prompt images require instructions explaining their role.

Create standalone images and video clips

Standalone photos use mode: "photos" and an image format. They produce media rather than posts:

{
  "format": "slideshow",
  "mode": "photos",
  "prompt": "A tidy desk in soft morning light",
  "faceless": true,
  "photoCount": 1,
  "aspectRatio": "9:16",
  "idempotency_key": "desk-photo-1"
}

A photo shoot needs an influencer, a prompt, reference media, or products. Use influencerId for an influencer shoot; personaMediaId can select an identity reference, otherwise their pinned photo is used. matchPersonaPhoto: false disables that photo reference. reshootFace: true rebuilds the reference set and pins the new face while retaining old photos. Prompt references (promptMediaIds) are not supported in photos mode.

Video clips use mode: "videos" with format: "video" or "hook_demo":

{
  "format": "video",
  "mode": "videos",
  "prompt": "A slow handheld view of a tidy desk",
  "videoDurationSeconds": 5,
  "idempotency_key": "desk-clip-1"
}

Choose a videoTemplate from Studio options or describe custom motion. Do not send both a fixed motion and a custom-motion prompt unless prompt references explain what should change. The template must match whether the clip includes an influencer and/or one product. Ordinary video offers 5, 10, 15, 20, or 30 seconds; a hook clip uses its own fixed short duration. A remix creates a post, not a standalone clip.

Use get_job, then get_media_url for returned media IDs. To turn finished media into an editable post, use create_uploaded_content even when the media came from generation rather than an upload.

Remix a source

Call prepare_remix with exactly one discover_id or source. Source options cover supported URLs, pasted text, or existing uploaded media; the reference contains the complete union.

{
  "source": {
    "kind": "pasted",
    "text": "Three ways to keep a desk tidy: sort cables into labeled clips, clear the surface at the end of each day, and give every small item a dedicated storage spot."
  }
}

Preparation costs no generation credits. It returns the analyzed source, a proposed format, prompt, skeleton, and analysisToken. For generation, pass the returned skeleton as remixSkeleton and token as remixAnalysisToken; preserve the signed structure. Use supported separate fields such as openingTextMode and openingText to request opening-text changes rather than modifying the signed skeleton.

Source availability, supported format combinations, reference ownership, and content rules are checked by the app routes. Preparing a source is not permission to publish it or a guarantee that every source can be recreated.

Jobs and video frame approval

Read progress with:

{
  "job_id": "44444444-4444-4444-8444-444444444444"
}

list_jobs returns active work in the workspace. Jobs can be queued, running, waiting_provider, awaiting_review, completed, failed, or cancelled. Read the actual returned status, progressStage, canCancel, canRetry, error, and result rather than deriving capabilities from the status alone.

For post generation that draws opening frames, reviewFrames: true can pause before rendering. At awaiting_review, show every frameReview.frames[].url, its reshootsLeft, and frameReview.expiresAt. Ask the customer to approve or specify a reshoot.

Call approve_video_frames with job_id and a key only after approval. To reshoot, call reshoot_video_frame with the zero-based index, optional note (up to 300 characters), and a key. Subsequent frames are also redrawn. Both actions return queued work; poll again. Review expires, after which the app cancels it and returns the reserved credits under its rules.

Use cancel_job only when canCancel is true. Already-spent work cannot be stopped just because it appears queued again. canRetry can indicate an app retry is available; there is no MCP customer tool for that manual job retry. A failed or cancelled result should be reported, not automatically regenerated at another cost.

Edit posts, images, and videos

Read get_content before a slide save. Preserve fields the customer did not ask to change and send the entire edited list. Each slide has required mediaId (nullable by schema), timelineDurationMs, label, mediaFrame, trimInMs, trimOutMs, and key; the full schema contains defaults and optional overlays, audio, layout, motion, and grading.

Visual and audio rows need media. A text row needs one nonblank overlay box, a duration, no media, and track index zero. Audio rows cannot contain visual overlays or a cutout. A collage must supply the correct number of cells and can only belong to a visual row. The list supports 1–40 items.

Video timeline saves can queue a render without returning a generation jobId. Poll get_content until the saved version is rendered: renderStatus is idle with a rendered file, renderStale is false, and the rendered revision matches the timeline revision. Do not publish stale media.

For a multiply, counts are 1–5 per target with a total limit of 25. replaceSource: true requires influencer mode and exactly one version per target. It replaces the source's place in the deck and has photo-based pricing rather than ordinary variation pricing.

Upload a real file

1. Call prepare_media_upload with its real MIME type and byte size (positive, at most 262,144,000 bytes, or 250 MiB).

{
  "mimeType": "image/jpeg",
  "fileSize": 1048576,
  "idempotency_key": "desk-upload-intent-1"
}

1. Transfer the actual file bytes outside MCP using the returned instructions. The client needs filesystem and HTTP-transfer capability; an assistant that cannot upload bytes must hand this step to a capable client or the customer.

1. Only after all bytes upload successfully, call complete_media_upload with the returned storagePath and mimeType, plus uploadId for multipart storage. Use purpose: "general" for Library media or post_own_file, and purpose: "remix_source" for prepare_remix. General Library media cannot be used as a remix upload. influencerId can attach media to an influencer. The result's id is the media ID.
2. Use abort_media_upload with storagePath and uploadId if a multipart upload fails. If a signed upload URL expires, prepare a new upload with a new key.

Never substitute a local path for a server URL or invent base64 content. Use the MIME types enumerated by the reference. Recording reference-face or voice consent may be required before registering or using those assets.

Post your own file

Complete the upload first, ask whether each uploaded asset is AI-generated, and look up an existing connected account. Then:

{
  "format": "slideshow",
  "media_ids": ["22222222-2222-4222-8222-222222222222"],
  "account_id": "33333333-3333-4333-8333-333333333333",
  "when": "2026-10-15",
  "caption": "Our new desk setup",
  "mediaAiDeclarations": [
    {
      "mediaId": "22222222-2222-4222-8222-222222222222",
      "isAiGenerated": false
    }
  ],
  "idempotency_key": "desk-own-file-1"
}

post_own_file accepts slideshow, wall_of_text, or video, 1–20 media IDs, and when: "now" or a valid day. A video must be one finished clip. A slideshow can use several images. The app validates media kinds and publishing readiness. This action creates a private post and then queues scheduling/publishing without generation credits.

The success result contains content and post. It does not establish delivery. If scheduling fails after creation, the error contains the saved content_id. Fix the cause and schedule or publish that draft, with a new key for that recovery action. Do not repeat uploads or create a second draft.

For editing before publication, use create_uploaded_content with slides: [{ "mediaId": "..." }], then edit and schedule the returned post.

Influencers and consent

Influencers are your reusable AI creators. list_influencers reads the roster. draft_influencer_identity proposes an identity from brand context; draft_influencer_character completes its character. These draft tools return data to review, not a saved influencer. Save accepted values with create_influencer or update_influencer. redraft_influencer_character produces another character draft to save explicitly.

create_influencer requires a name, costs 125 credits once, and includes the first face shoot. If supplied, age must be 18–99. Identity, character (bible), profile configuration, reference-photo IDs, and voice fields follow the reference. Archive with update_influencer and the supported archived status. Editing identity fields does not itself redraw an existing face; use a photos-mode face reshoot if requested.

Use preset voice settings through update_influencer. To clone a voice, first upload the customer's recording, ask for explicit voice-clone permission, read the current consent version/purpose from Studio options, record it with record_media_consent and confirm: true, then call clone_influencer_voice with influencer_id and mediaId. The result includes speakingVoiceId and auditionUrl.

Face-reference permission follows the same explicit-answer flow with the reference-face purpose. Never infer either permission from a file upload or generation brief. The reference schema has permissive custom fields for bible; use the actual character draft response rather than inventing a shape.

delete_influencer permanently deletes an influencer and releases their cloned voice; it requires an explicit deletion request and confirm: true. delete_media also requires confirmation and remains subject to the app's use/ownership rules.

Connect and manage social accounts

Read list_accounts, get_account, and get_account_activity for current state. To connect Instagram or TikTok:

1. Call start_account_connection with platform, optional influencerId, and a key. For reconnecting a released account, supply its accountId.
2. Give the customer the returned connectUrl to complete provider sign-in. Do not ask for their platform password. attemptId is the authorization attempt, not yet a connected account.
3. Call complete_account_connection with that attempt ID as account_id and a key. A pending result means authorization is not finished; connected returns the account. Use a fresh key for a later check so the earlier pending response is not replayed.

update_account changes supported identity settings, influencer assignment, learning, and pause state. paused: true pauses; paused: false resumes. Resuming a released account can reserve credits. Some settings are locked by account readiness/type rules.

manage_account_connection returns a provider link to reconnect or revoke an account; the customer completes it in the provider screen. reconcile_account refreshes state afterward. delete_account disconnects/deletes under existing app rules and can stop scheduled posting. It requires an explicit request and confirm: true.

Connecting a social account is separate from connecting the AI client to Amplify. The former may reserve account credits; the latter chooses the assistant's permissions and daily ceiling.

Schedule, publish, and check status

Use schedule_post with contentItemId, accountId, a required when day (YYYY-MM-DD), and a key. Use publish_content with the same IDs and disclosure fields when the customer asks to publish immediately; it sets when: "now" itself.

Per-post options are caption, hashtags, isPaidPartnership, and mediaAiDeclarations. AI disclosure answers must refer to media actually included in the post and requiring confirmation. Generated media is known by the app; ask about unknown uploaded assets. hashtags: null inherits the post's tags, [] uses only the brand's pinned tags, and a populated array supplies the platform-specific set.

reschedule_post takes post_id and a new required day. cancel_post uses post_id and only works before posting. publish_scheduled_post queues an existing post immediately or retries a failed post when requested. It does not bypass account or render gates.

Dates are account-local calendar days. Self-connected accounts use the app's available posting slots; managed accounts use their country-local day and the operator's minimum 24-hour lead time. Managed accounts cannot publish immediately. The app allows at most two posts per account per local day. A full day or an account that is not ready requires another allowed day or resolved setup.

After any publishing call, use get_calendar with month or from/to ISO ranges to read the post's status, externalUrl, postedAt, failureCode, and failureMessage. Use get_account_activity for account events and queue context. Only a final posted outcome establishes delivery.

Use get_insights for workspace results and learning, optionally filtered by accountId. Posting delivery and later metrics availability are different outcomes.

Retry without duplicating work

Preserve the mutation key and input when recovering a lost response. Inspect jobs, posts, and Calendar before starting a new action after an uncertain outcome. See retry and recovery rules, including the 24-hour retention, the 72-hour account-connection exception, pending completion snapshots, and partial own-file recovery.