# SimilarClip: guide for AI agents > SimilarClip turns a topic or a YouTube link into a narrated, fully illustrated YouTube video and can publish it for you, once or on a schedule. This file is everything an agent needs to drive it end to end. ## What it makes - Topic videos: you give a subject ("the Great Emu War"). SimilarClip researches it, picks an angle, writes an original 3–15 minute script, and produces the video. - Reimagined videos: you give a YouTube URL that has captions. SimilarClip rewrites the transcript into a new script with new visuals and a new voice. - Every video comes with a new AI image every ~5 seconds in a chosen style (each image storyboarded from the line being spoken with the whole script in view, the story's key subjects described once and drawn the same way everywhere, and vision-checked and redrawn up to twice for wrong subjects, mangled hands, stray text or a poor match), a voice-over, word-by-word burned-in captions with key words popping up as they're spoken, motion on every image with hard cuts, background music, sound effects, a thumbnail, and a YouTube title (plus alternatives), description and tags. - Topic scripts open on the most gripping moment first (cold open) and are sized to hit the requested length. - Publishing goes to the user's connected YouTube channels, with AI-content disclosure on by default. ## 1. Get access (one-time, needs the human) 1. The human creates an account at https://similarclip.com/signup. 2. They pick a plan at https://similarclip.com/app/billing. You can also send them a link from `create_checkout`. 3. They create an API key at https://similarclip.com/app/settings?tab=api and give it to you. Keys look like `sc_live_…`. Treat the key as a secret: it can spend the account's credit and publish to its channels. 4. Optional: they connect YouTube channels at https://similarclip.com/app/settings (Google sign-in). ## 2. Connect ### MCP (recommended for agents) Streamable HTTP endpoint: `https://similarclip.com/mcp`. Authenticate with `Authorization: Bearer `. The server is stateless and needs no session handling. Claude Code: ```sh claude mcp add --transport http similarclip https://similarclip.com/mcp --header "Authorization: Bearer sc_live_YOUR_KEY" ``` Clients that read an `mcpServers` JSON config (Cursor, Windsurf, VS Code and others): ```json { "mcpServers": { "similarclip": { "type": "http", "url": "https://similarclip.com/mcp", "headers": { "Authorization": "Bearer sc_live_YOUR_KEY" } } } } ``` Clients that only support stdio servers (via mcp-remote): ```json { "mcpServers": { "similarclip": { "command": "npx", "args": [ "-y", "mcp-remote", "https://similarclip.com/mcp", "--header", "Authorization: Bearer sc_live_YOUR_KEY" ] } } } ``` ### REST Base URL `https://similarclip.com/api/v1`. Send JSON bodies and the same `Authorization: Bearer ` header (or `X-API-Key`). The OpenAPI spec is at https://similarclip.com/openapi.json. ```sh curl -X POST https://similarclip.com/api/v1/videos \ -H "Authorization: Bearer sc_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"topic": "why octopuses have three hearts", "duration_min": 5, "publish": {"visibility": "unlisted"}}' ``` ## 3. Workflows ### Make a video and publish it 1. `get_account`: confirm `can_generate` is true. If it isn't, follow `next_step`. 2. `get_options`: pick a style and voice from the valid lists, or omit them to use the account's saved defaults. 3. `create_video` with `topic` (or `youtube_url`), plus optional `duration_min`, `style`, `voice`, and `publish: { "visibility": "public" | "unlisted" | "private", "channel_id"?: "…" }`. 4. Poll `get_video` every 30–60 seconds. `status` moves from queued to processing to completed (or failed). `progress_pct` and `current_step` show where it is. 5. When it completes: `video_url` is the MP4 and `thumbnail_url` the thumbnail. If you set `publish`, the upload starts automatically. Otherwise call `publish_video`. 6. Poll `get_video` until `publication.status` is `published`, then share `publication.youtube_url`. ### Buy a plan or credit 1. `get_billing` lists the plans, the balance, and the estimated cost per minute of video. 2. `create_checkout` with `{ "type": "subscription", "plan": "pro" }` or `{ "type": "topup", "pack": "10min" }` returns a `checkout_url`. 3. Give the link to your human. Payment always happens on Stripe and is approved by a person. 4. Poll `get_billing` or `get_account` until the plan or credit shows up, then continue. A video refused for billing comes back with `details.video_id`. Restart it with `start_video`. ### Vet scripts before paying for videos 1. `create_video` with `review_script: true` (and optionally an `idempotency_key`). Only research and scripting run. 2. Wait for `status: script_ready` (poll `get_video` or use the `video.script_ready` webhook). 3. `get_script` returns the lines, word count and estimated length. Rewrite, add or drop lines with `update_script`. 4. `approve_script` renders it (the credit check happens here). `delete_video` throws a weak script away. ### Fix one part of a finished video - `list_scenes` returns every line and every image with its URL, ids, storyboarded visual and image-check result. - If a setting seems to have had no effect, `get_video`'s `render` shows what the last render actually contained: `story_sound_cues` (with `story_sound_cue_kinds`, e.g. crowd, rain, splash) are sound effects for events in the story, counted apart from `ui_sounds` (soft ticks under pop-up words). `render.measured` is taken from the render itself: `motion_pct` is the median pixel change within single images measured on the image layer only, before captions and pop-up words are burned in (still images measure about 0; Ken Burns motion 2 or more), `moving_slides_pct` is the share of images that visibly move, and `story_cue_peak_vs_voice_db` / `ui_sound_peak_vs_voice_db` are how loud each family peaks against the voice's average level (+5 dB or more is clearly audible; null means none played). - `get_video.cost_breakdown` shows where a finished video's money went (images, image_redraws, image_checks, storyboard, script, voiceover, …) and `models` which AI models were used. Raise `seconds_per_image` or turn `image_check` off to spend less; `estimate_video_cost` takes both. - `regenerate_slide_image` redraws one image; `regenerate_scene_image` redraws a scene's images. - `edit_scene_line` changes one line: only that line is re-voiced and its images redrawn. - `regenerate_voice` re-narrates everything (optionally with a new voice), keeping the images. - `update_video_settings` changes captions, pop-up words, motion, transitions, music or sound effects and re-renders from the existing assets with no new AI generation. - `set_video_metadata` sets your own title, description, tags or thumbnail headline; `regenerate_thumbnail` draws another thumbnail. ### Learn from results `get_video_stats` returns YouTube views, likes and comments for published videos next to the topic, style, voice and creative settings each was made with. Watch time and average view percentage are not available yet (they need an extra Google permission). ### Get notified instead of polling `create_webhook` with an https URL. Events: `video.script_ready`, `video.completed`, `video.failed`, `video.published`, `video.publish_failed` (every dropped or failed publish carries the reason). Verify `X-SimilarClip-Signature: t=,v1=`, where v1 is HMAC-SHA256 of `.` under the secret returned once at creation. ### Put a channel on autopilot 1. `create_schedule` with `name`, `niche`, `frequency` (daily, every_2_days or weekly), `time_of_day`, `timezone`, a style and voice, and `auto_publish`. 2. Fill the queue: pass `topics` when creating it, call `add_schedule_topics`, or call `generate_schedule_topics` to have the AI brainstorm topics from the niche. 3. Each run turns the next topic into a video and publishes it. `get_schedule` shows the queue and the video each topic produced. `run_schedule_now` runs it immediately. ### Recover from problems - `failed` with `error.resumable: true`: call `resume_video`. It continues from the failed step and keeps finished work. - `failed` with `error.resumable: false`: the input can't be used. Create a new video. - `publication.status: failed`: read `publication.error`. It is usually a disconnected channel. Ask the human to reconnect, then call `publish_video` again. ## 4. Creative options Always confirm against `get_options`, which is authoritative and also returns the account's defaults. Styles: colorful-doodle, stick-drawing, storybook, flat-vector, anime, cinematic, claymation, comic-book, pixel-art, watercolor, 3d-isometric. You can also set `custom_style_prompt` with your own art direction. Voices by provider: - xai: eve, ara, rex, sal, leo - google: zephyr, puck, charon, kore, fenrir, leda, orus, aoede, callirrhoe, autonoe, enceladus, iapetus, umbriel, algieba, despina, erinome, algenib, rasalgethi, laomedeia, achernar, alnilam, schedar, gacrux, pulcherrima, achird, zubenelgenubi, vindemiatrix, sadachbia, sadaltager, sulafat Vibes: storyteller, professional, cheerleader, dramatic, sincere, calm. You can also set `voice.instructions` with your own delivery notes. Speeds: 1, 1.25, 1.5. The default for new accounts is the energetic storyteller vibe. Creative settings (`creative` on create_video, create_schedule and update_video_settings): - `captions` (default on), `caption_style`: word | phrase (word = one line with the spoken word lit up) - `pop_words` (default on): each scene's key word or number pops up big as it is spoken - `motion` (default on): a slow pan or zoom on every image; false = still images - `seconds_per_image`: 2-15 (default 5; fewer seconds = more images = more cost, and a faster, busier edit) - `transition`: cut | crossfade | fade (default cut) - `music_volume`: 0-100 (default 50; 0 = no music), `sound_effects` (default on: story cues for what happens in the narration — a crowd roaring, rain, a splash, a crash, a siren — landing on the word they happen on, plus soft ticks under pop-up words; image and scene changes are silent) - `hook_style`: cold_open | bold_claim | question | story (default cold_open) - `image_check` (default on): redraw images (up to twice) with a wrong or stray subject, mangled hands or faces, stray text or emblems, or a poor match to the line; also keeps pop-up words off faces Voice previews: https://similarclip.com/voice-samples/{voice}__{vibe}.mp3 ## 5. Tool reference Each tool exists both as an MCP tool and as a REST endpoint. REST takes path parameters in the URL, query parameters for GET, and a JSON body for POST. ## Account ### get_account `GET /api/v1/me` · MCP tool `get_account` Who the API key belongs to, plan/subscription status, AI credit balance, connected YouTube channels and saved defaults (style, voice, description footer). Call this first to see what the account can do. ### update_account_settings `POST /api/v1/me/settings` · MCP tool `update_account_settings` Account-wide defaults that create_video and create_schedule use when a field is omitted: style, custom_style_prompt and voice (provider, voice, vibe, instructions, speed), plus description_footer, appended to every YouTube description this account publishes (links, socials, a call to action). Omitted fields are left as they are; "" clears custom_style_prompt, voice.instructions or description_footer. Returns the saved settings. Parameters: - `style`: "colorful-doodle" | "stick-drawing" | "storybook" | "flat-vector" | "anime" | "cinematic" | "claymation" | "comic-book" | "pixel-art" | "watercolor" | "3d-isometric": Default visual style preset (see get_options). - `custom_style_prompt`: string (≤2000 chars): Default free-form art direction; overrides the preset when set. "" clears it. - `voice`: { provider?: "xai" | "google", voice?: string, vibe?: "storyteller" | "professional" | "cheerleader" | "dramatic" | "sincere" | "calm", instructions?: string (≤1000 chars), speed?: 1 | 1.25 | 1.5 }: Narration voice. Omitted fields use the account's saved defaults. - `description_footer`: string (≤1000 chars) ## Billing ### get_billing `GET /api/v1/billing` · MCP tool `get_billing` Credit balance (plan credit + credit packs), the current plan, the purchasable plans (monthly and annual), credit packs and the estimated cost per minute of video. Use it to work out whether a video is affordable before creating it. ### create_checkout `POST /api/v1/billing/checkout` · MCP tool `create_checkout` Start a purchase for the account: a subscription plan (monthly or annual) or a one-time credit pack (needs an active plan). Returns a checkout_url that a HUMAN must open to pay (agents never handle card details). Share the link with your user, wait for them to confirm, then check get_billing. Parameters: - `type` (required): "subscription" | "topup" - `plan`: string: Plan name for type=subscription (see get_billing.plans). - `annual`: boolean: type=subscription: bill yearly (10 months' price for 12; credit is still granted monthly). - `pack`: "10min" | "30min": Credit pack for type=topup (see get_billing.credit_packs). ## Videos ### get_options `GET /api/v1/options` · MCP tool `get_options` Every valid value for create_video and create_schedule: visual style presets (with their art direction), TTS providers and voices, narration vibes, speeds, duration limits and visibilities. Also returns this account's saved defaults. ### estimate_video_cost `GET /api/v1/videos/estimate` · MCP tool `estimate_video_cost` Estimated USD cost of a video of the given length, compared with the current balance. Calibrated from this account's own recent videos when it has at least 3 (else the platform rate), and scaled by seconds_per_image and image_check, since images are most of the cost. Real billing is metered at exact AI cost; get_video.cost_breakdown shows where a finished video's money went. Parameters: - `duration_min`: number (0.25–15), default 5 - `seconds_per_image`: number (2–15): Planned seconds per image (default 5). More seconds = fewer images = cheaper. - `image_check`: boolean: Planned image check setting (default on; off saves ~15%). ### create_video `POST /api/v1/videos` · MCP tool `create_video` Generate a narrated, fully illustrated video. Give EITHER `topic` (SimilarClip researches it, picks an angle and writes an original script) OR `youtube_url` (it reimagines that clip with a fresh script, new visuals and a new voice; the source needs captions). Generation is asynchronous and takes several minutes: poll get_video until status is "completed" or "failed". Set `publish` to upload to YouTube automatically when done. Parameters: - `topic`: string (≤500 chars): What the video is about, e.g. "why octopuses have three hearts". - `youtube_url`: string: A YouTube video to reimagine (must have captions). - `duration_min`: integer (3–15): Target length for topic videos, in minutes. - `style`: "colorful-doodle" | "stick-drawing" | "storybook" | "flat-vector" | "anime" | "cinematic" | "claymation" | "comic-book" | "pixel-art" | "watercolor" | "3d-isometric": Visual style preset (see get_options). - `custom_style_prompt`: string (≤2000 chars): Free-form art direction; overrides the preset when set. - `voice`: { provider?: "xai" | "google", voice?: string, vibe?: "storyteller" | "professional" | "cheerleader" | "dramatic" | "sincere" | "calm", instructions?: string (≤1000 chars), speed?: 1 | 1.25 | 1.5 }: Narration voice. Omitted fields use the account's saved defaults. - `creative`: { captions?: boolean, caption_style?: "word" | "phrase", pop_words?: boolean, motion?: boolean, seconds_per_image?: number (2–15), transition?: "cut" | "crossfade" | "fade", music_volume?: number (0–100), sound_effects?: boolean, hook_style?: "cold_open" | "bold_claim" | "question" | "story", image_check?: boolean }: Creative settings for this video. Omitted fields use the account's settings, then SimilarClip's defaults. - `title`: string (≤100 chars): Your own YouTube title; wins over the generated one. - `description`: string (≤5000 chars): Your own YouTube description; wins over the generated one. - `tags`: string (≤100 chars)[]: Your own YouTube tags. - `review_script`: boolean, default false: true = stop once the script is written (status script_ready) so you can read, edit and approve it before paying for voice, images and rendering. Cheap way to vet many ideas. - `publish`: { visibility?: "public" | "unlisted" | "private", description_footer?: string (≤1000 chars), channel_id?: string, contains_synthetic_media?: boolean }: Publish to YouTube automatically when the video completes. - `start`: boolean, default true: false = create a draft only; start it later with start_video. - `idempotency_key`: string (≤200 chars): Any unique string (e.g. a UUID). Retrying with the same key returns the first call's result instead of acting, and charging, twice. REST clients can send an Idempotency-Key header instead. ### list_videos `GET /api/v1/videos` · MCP tool `list_videos` The account's videos, newest first. Filter by status to find running or finished ones. Parameters: - `status`: "draft" | "queued" | "processing" | "script_ready" | "completed" | "failed" | "paused" | "stopped" - `limit`: integer (1–100), default 20 ### get_video `GET /api/v1/videos/{id}` · MCP tool `get_video` Full status of one video: progress, current pipeline step, errors (and whether they are resumable), the downloadable MP4 and thumbnail URLs once completed, generated YouTube SEO metadata, the latest YouTube publication, the resolved creative settings, and `render`: what the last render actually contained (motion, transition, caption style, pop-up word count, music, sound-effect count). Check `render` when a setting seems to have no effect. Parameters: - `id` (required): string: Video id. ### start_video `POST /api/v1/videos/{id}/start` · MCP tool `start_video` Start generating a draft video (one created with start=false, or refused earlier for billing). Parameters: - `id` (required): string ### resume_video `POST /api/v1/videos/{id}/resume` · MCP tool `resume_video` Resume a paused video, or retry a failed one from the step it stopped at (when error.resumable is true). Parameters: - `id` (required): string ### pause_video `POST /api/v1/videos/{id}/pause` · MCP tool `pause_video` Pause a queued or processing video at the next step boundary. Resume later with resume_video. Parameters: - `id` (required): string ### stop_video `POST /api/v1/videos/{id}/stop` · MCP tool `stop_video` Stop a running or paused video for good (it cannot be resumed afterwards). Parameters: - `id` (required): string ### delete_video `DELETE /api/v1/videos/{id}` · MCP tool `delete_video` Permanently delete a video and its files. Running videos must be stopped first. Already-published YouTube uploads are not touched. Parameters: - `id` (required): string ### get_script `GET /api/v1/videos/{id}/script` · MCP tool `get_script` The video's script, line by line (one line per scene), with word count and estimated narration length. Use it on a script_ready video before approve_script, or on any video to read what is narrated. Parameters: - `id` (required): string ### update_script `POST /api/v1/videos/{id}/script` · MCP tool `update_script` Replace the script of a script_ready video. Send every line in order: lines with a scene_id keep that scene (its text replaced), lines without one are new scenes, and scenes you leave out are deleted. To change lines of an already rendered video use edit_scene_line instead. Parameters: - `id` (required): string - `lines` (required): { scene_id?: string, text: string (≤1500 chars) }[] ### approve_script `POST /api/v1/videos/{id}/script/approve` · MCP tool `approve_script` Render a script_ready video: narration, images, captions, music and the final video. This is where most of the cost is spent, so it passes the same credit check as start_video. Parameters: - `id` (required): string ### update_video_settings `POST /api/v1/videos/{id}/settings` · MCP tool `update_video_settings` Change a video's creative settings. On a completed or failed video, caption, pop-word, motion, transition, music and sound-effect changes re-render it from the existing images and voice (cheap, no new AI generation). seconds_per_image, hook_style and image_check only affect steps that haven't run yet. Parameters: - `id` (required): string - `creative` (required): { captions?: boolean, caption_style?: "word" | "phrase", pop_words?: boolean, motion?: boolean, seconds_per_image?: number (2–15), transition?: "cut" | "crossfade" | "fade", music_volume?: number (0–100), sound_effects?: boolean, hook_style?: "cold_open" | "bold_claim" | "question" | "story", image_check?: boolean }: Creative settings for this video. Omitted fields use the account's settings, then SimilarClip's defaults. - `rerender`: boolean, default true: Re-render a finished video to apply the change. ## Scenes ### list_scenes `GET /api/v1/videos/{id}/scenes` · MCP tool `list_scenes` Every scene of a video in order: its narration line, timing, and each image (slide) shown during it, with the image URL, the exact words it illustrates, the storyboarded visual it was drawn from, and the image check result (passed, redraws, issues). Also returns the key subjects every image was told to draw accurately. Use the ids with edit_scene_line, regenerate_scene_image and regenerate_slide_image. Parameters: - `id` (required): string ### edit_scene_line `POST /api/v1/videos/{id}/scenes/{scene_id}` · MCP tool `edit_scene_line` Change one scene's narration on a completed or failed video. Only that line is re-voiced and only its images are redrawn; every other scene, the SEO and the thumbnail are kept, and the video is re-rendered. Parameters: - `id` (required): string - `scene_id` (required): string - `text` (required): string (≤1500 chars) ### regenerate_scene_image `POST /api/v1/videos/{id}/scenes/{scene_id}/regenerate-images` · MCP tool `regenerate_scene_image` Redraw every image of one scene (text and voice untouched), then re-render the video. Parameters: - `id` (required): string - `scene_id` (required): string ### regenerate_slide_image `POST /api/v1/videos/{id}/slides/{slide_id}/regenerate` · MCP tool `regenerate_slide_image` Redraw a single image (slide) — e.g. one with a mangled hand or a poor match — then re-render the video. Everything else is kept. Parameters: - `id` (required): string - `slide_id` (required): string ### regenerate_voice `POST /api/v1/videos/{id}/regenerate-voice` · MCP tool `regenerate_voice` Re-narrate a completed or failed video, optionally with a different voice, vibe or speed. Images, SEO and thumbnail are kept; image timing follows the new narration. Parameters: - `id` (required): string - `voice`: { provider?: "xai" | "google", voice?: string, vibe?: "storyteller" | "professional" | "cheerleader" | "dramatic" | "sincere" | "calm", instructions?: string (≤1000 chars), speed?: 1 | 1.25 | 1.5 }: Narration voice. Omitted fields use the account's saved defaults. ## YouTube ### publish_video `POST /api/v1/videos/{id}/publish` · MCP tool `publish_video` Upload a completed video to one of the account's connected YouTube channels, with the generated thumbnail. Title/description/tags default to the AI-generated SEO metadata. The upload runs in the background: poll get_video and read `publication` for the YouTube URL. Parameters: - `visibility`: "public" | "unlisted" | "private", default "public" - `description_footer`: string (≤1000 chars): Appended to the YouTube description (links, socials). Omit to use the account's default footer; "" for none. - `channel_id`: string: Connected channel to upload to (from list_youtube_channels). Omit for the default channel. - `contains_synthetic_media`: boolean, default true: YouTube's altered/synthetic content disclosure. SimilarClip videos are AI-generated, so keep true. - `id` (required): string - `title`: string (≤100 chars) - `description`: string (≤5000 chars) - `tags`: string (≤100 chars)[] - `idempotency_key`: string (≤200 chars): Any unique string (e.g. a UUID). Retrying with the same key returns the first call's result instead of acting, and charging, twice. REST clients can send an Idempotency-Key header instead. ### set_video_metadata `POST /api/v1/videos/{id}/metadata` · MCP tool `set_video_metadata` Set your own YouTube title, description, tags and/or thumbnail headline (pick from get_video.seo_options or write your own). Applies now on a finished video and survives any later re-render. Changing thumbnail_headline also redraws the thumbnail. Parameters: - `id` (required): string - `title`: string (≤100 chars): Your own YouTube title; wins over the generated one. - `description`: string (≤5000 chars): Your own YouTube description; wins over the generated one. - `tags`: string (≤100 chars)[]: Your own YouTube tags. - `thumbnail_headline`: string (≤40 chars): 2-4 words lettered on the thumbnail. ### regenerate_thumbnail `POST /api/v1/videos/{id}/thumbnail/regenerate` · MCP tool `regenerate_thumbnail` Redraw a completed video's thumbnail, optionally with a new headline (e.g. one of get_video.seo_options.thumbnail_headlines). Call it again for another variant. Parameters: - `id` (required): string - `headline`: string (≤40 chars) ### get_video_stats `GET /api/v1/youtube/stats` · MCP tool `get_video_stats` Live YouTube views, likes and comments for the account's published videos, next to the settings each was made with (topic, style, voice, vibe, creative settings, length), so you can learn what works. Pass video ids, or omit them for the 50 most recent. Parameters: - `video_ids`: string[] | string: SimilarClip video ids (array, or comma-separated in a query string). ### list_youtube_channels `GET /api/v1/youtube/channels` · MCP tool `list_youtube_channels` The YouTube channels connected to the account for publishing. Connecting a channel needs a human (Google OAuth): if none are connected, give your user the connect_url. ## Schedules ### list_schedules `GET /api/v1/schedules` · MCP tool `list_schedules` Autopilot schedules: each turns a queue of topics into videos on a cadence (daily, every 2 days, weekly) and can auto-publish them to YouTube. ### get_schedule `GET /api/v1/schedules/{id}` · MCP tool `get_schedule` One schedule with its topic queue (pending, generating, completed, failed topics and their video ids). Parameters: - `id` (required): string ### create_schedule `POST /api/v1/schedules` · MCP tool `create_schedule` Put a channel on autopilot: SimilarClip produces one video per run from the topic queue (queue topics via `topics`, add_schedule_topics or generate_schedule_topics; a run with an empty queue is skipped) and optionally auto-publishes each to YouTube. Parameters: - `name` (required): string (≤100 chars) - `niche` (required): string (≤500 chars): The channel's niche/theme, e.g. "weird animal facts". - `frequency`: "daily" | "every_2_days" | "weekly", default "daily" - `time_of_day`: string, default "09:00": 24h local time, HH:MM. - `timezone`: string, default "UTC": IANA timezone, e.g. America/New_York. - `duration_min`: integer (3–15), default 5 - `style`: "colorful-doodle" | "stick-drawing" | "storybook" | "flat-vector" | "anime" | "cinematic" | "claymation" | "comic-book" | "pixel-art" | "watercolor" | "3d-isometric" - `custom_style_prompt`: string (≤2000 chars) - `voice`: { provider?: "xai" | "google", voice?: string, vibe?: "storyteller" | "professional" | "cheerleader" | "dramatic" | "sincere" | "calm", instructions?: string (≤1000 chars), speed?: 1 | 1.25 | 1.5 }: Narration voice. Omitted fields use the account's saved defaults. - `auto_publish`: boolean, default true - `visibility`: "public" | "unlisted" | "private", default "public" - `channel_id`: string: Connected channel to auto-publish to; omit for the default. - `topics`: string (≤500 chars)[]: Initial topic queue. - `creative`: { captions?: boolean, caption_style?: "word" | "phrase", pop_words?: boolean, motion?: boolean, seconds_per_image?: number (2–15), transition?: "cut" | "crossfade" | "fade", music_volume?: number (0–100), sound_effects?: boolean, hook_style?: "cold_open" | "bold_claim" | "question" | "story", image_check?: boolean }: Creative settings for this video. Omitted fields use the account's settings, then SimilarClip's defaults. - `description_footer`: string (≤1000 chars): Appended to each auto-published description; omit for the account default. - `idempotency_key`: string (≤200 chars): Any unique string (e.g. a UUID). Retrying with the same key returns the first call's result instead of acting, and charging, twice. REST clients can send an Idempotency-Key header instead. ### add_schedule_topics `POST /api/v1/schedules/{id}/topics` · MCP tool `add_schedule_topics` Append topics to a schedule's queue (duplicates are skipped). One topic is consumed per run. Parameters: - `id` (required): string - `topics` (required): string (≤500 chars)[] ### generate_schedule_topics `POST /api/v1/schedules/{id}/topics/generate` · MCP tool `generate_schedule_topics` Have the AI brainstorm fresh, non-duplicate topics from the schedule's niche and append them to its queue. Parameters: - `id` (required): string - `count`: integer (1–20), default 10 ### update_schedule `POST /api/v1/schedules/{id}` · MCP tool `update_schedule` Change any of a schedule's settings. Only the fields you send change. Changing frequency, time_of_day or timezone re-plans the next run. Parameters: - `id` (required): string - `name`: string (≤100 chars) - `niche`: string (≤500 chars) - `frequency`: "daily" | "every_2_days" | "weekly" - `time_of_day`: string - `timezone`: string - `duration_min`: integer (3–15) - `style`: "colorful-doodle" | "stick-drawing" | "storybook" | "flat-vector" | "anime" | "cinematic" | "claymation" | "comic-book" | "pixel-art" | "watercolor" | "3d-isometric" - `custom_style_prompt`: string (≤2000 chars) | null - `voice`: { provider?: "xai" | "google", voice?: string, vibe?: "storyteller" | "professional" | "cheerleader" | "dramatic" | "sincere" | "calm", instructions?: string (≤1000 chars), speed?: 1 | 1.25 | 1.5 }: Narration voice. Omitted fields use the account's saved defaults. - `auto_publish`: boolean - `visibility`: "public" | "unlisted" | "private" - `channel_id`: string | null: null = the default channel. - `creative`: { captions?: boolean, caption_style?: "word" | "phrase", pop_words?: boolean, motion?: boolean, seconds_per_image?: number (2–15), transition?: "cut" | "crossfade" | "fade", music_volume?: number (0–100), sound_effects?: boolean, hook_style?: "cold_open" | "bold_claim" | "question" | "story", image_check?: boolean }: Merged into the schedule's existing creative settings. - `description_footer`: string (≤1000 chars) | null ### delete_schedule `DELETE /api/v1/schedules/{id}` · MCP tool `delete_schedule` Delete a schedule and its topic queue. Videos it already made are kept. Parameters: - `id` (required): string ### delete_schedule_topic `DELETE /api/v1/schedules/{id}/topics/{topic_id}` · MCP tool `delete_schedule_topic` Remove a pending topic from a schedule's queue (topics already turned into videos stay in the history). Parameters: - `id` (required): string - `topic_id` (required): string ### set_schedule_enabled `POST /api/v1/schedules/{id}/enabled` · MCP tool `set_schedule_enabled` Turn a schedule on or off. Parameters: - `id` (required): string - `enabled` (required): boolean ### run_schedule_now `POST /api/v1/schedules/{id}/run` · MCP tool `run_schedule_now` Produce the schedule's next video immediately instead of waiting for its next slot. Parameters: - `id` (required): string ## Webhooks ### list_webhooks `GET /api/v1/webhooks` · MCP tool `list_webhooks` The account's webhook endpoints, the events each receives, and how the last delivery went. ### create_webhook `POST /api/v1/webhooks` · MCP tool `create_webhook` Have SimilarClip POST to your HTTPS endpoint when a video's script is ready, it completes or fails, or a publish succeeds or fails, instead of polling. The response includes the signing secret ONCE: verify X-SimilarClip-Signature (t=,v1=.">) with it. Failed deliveries retry with backoff for about 15 minutes. Parameters: - `url` (required): string (≤2000 chars): https:// endpoint on a public host. - `events`: "video.script_ready" | "video.completed" | "video.failed" | "video.published" | "video.publish_failed"[]: Events to receive; omit for all of them. ### delete_webhook `DELETE /api/v1/webhooks/{id}` · MCP tool `delete_webhook` Stop sending events to an endpoint. Parameters: - `id` (required): string ## 6. Errors REST errors look like `{ "error": { "code": "…", "message": "…", "details": { … } } }`. MCP tool errors come back as `isError: true` with the same JSON. - 400 `invalid_request`: the parameters failed validation. `details.issues` lists them. - 401 `missing_api_key` / `invalid_api_key`: ask the human for a valid key. - 402 `no_subscription` / `insufficient_credit`: call `create_checkout` and send the link to the human. - 404 `not_found`: unknown id, or the item belongs to another account. - 409: the video isn't in the right state, or YouTube isn't connected (`youtube_not_connected` includes a `connect_url`). - 422 `unusable_source`: the YouTube video is too long, has no captions, or is unavailable. - 409 `idempotency_in_progress`: a call with the same idempotency key is still running. 422 `idempotency_key_reused`: the key was used for a different tool. - 429 `rate_limited`: there are 120 requests per minute per key. Back off. ## 7. Pricing - Starter (`starter`): $39/month, includes $11 of AI credit per month (≈ 18 min of video) and 1 YouTube channel - Pro (`pro`): $99/month, includes $33 of AI credit per month (≈ 55 min of video) and 3 YouTube channels - Studio (`studio`): $199/month, includes $77 of AI credit per month (≈ 128 min of video) and 10 YouTube channels - Annual billing: 10 months' price for 12 (`create_checkout` with `annual: true`). Credit is still granted monthly. - Credit packs (need an active plan, never expire): `10min` ≈ 10 min for $25, `30min` ≈ 30 min for $69. - Every account needs an active plan to generate videos. - Credit packs can be bought any time on a plan (`create_checkout` with type topup). They never expire. ## 8. Limits and good manners - Topic videos run 3–15 minutes. Source YouTube videos must have captions and fit the length limit. - Each video is billed at its exact AI cost: plan credit first, then credit packs. Use `estimate_video_cost` before batch work. - Ask your human before spending a lot of credit, publishing publicly, or deleting anything. - Video URLs may be signed and expire. Call `get_video` again for a fresh one. - Not supported through YouTube's API yet: posting or pinning comments, playlists and end screens (YouTube offers no end-screen or pinning API at all).