---
name: shotto
description: Create Hebrew UGC ad videos with AI presenters, comic videos and automatic edits of the user's footage through the Shotto MCP server or REST API, spending the user's credits only after explicit confirmation.
---

# Shotto

Shotto (https://www.shottoai.com) is an Israeli service that makes short vertical ad videos **in Hebrew** for small
businesses. The product, the scripts, the voice and every API message are Hebrew; this file is English so any agent
can read it. Speak to the user in their language, but write briefs and scripts in Hebrew.

What it makes:
- **Presenter video**: an AI presenter says a Hebrew ad script, written by Shotto from a 2-line brief. 10, 20 or 30 s.
- **Comic video** (`format: "faceless"`): illustrated comic panels with a Hebrew voice-over, no presenter.
- **Automatic editing**: the user's own clips get captions, music, zooms and an optional end card.
- **Ad images**: on the website only (3 credits each); no API endpoint yet.

Full details, curl examples and error codes: [reference.md](reference.md).

## Connect

- MCP (preferred): `https://www.shottoai.com/mcp`, Streamable HTTP, header `Authorization: Bearer sk_shotto_…`.
  Claude Code: `claude mcp add --transport http shotto https://www.shottoai.com/mcp --header "Authorization: Bearer $SHOTTO_API_KEY"`
- REST: `https://www.shottoai.com/api/v1`, same header. See reference.md.
- The user creates the key at https://www.shottoai.com/settings/api. Never print or commit it.

## Credits (one wallet, same as the website)

| Action | Cost |
|---|---|
| Presenter video, regular quality (default) | 1 credit / second: 10 s = 10, 20 s = 20, 30 s = 30 |
| Presenter video, `quality: "hd"` | 2 credits / second: 10 s = 20, 20 s = 40, 30 s = 60 |
| Comic video (faceless) | 0.4 credit / second: 10 s = 4, 20 s = 8, 30 s = 12 (no quality option) |
| Editing the user's footage | first 60 s free (once per account), then 10 credits / minute (1 credit per 6 s, rounded up after a 1-second tolerance) |
| Script approval, status checks, presenters, balance | free |
| Ad image (website only) | 3 credits |

The charge happens **when the job is created**. If the script is never approved it expires and the credits return.
A technical failure also returns the credits automatically. Credits are bought only on https://www.shottoai.com
(subscriptions and credit packs); the API cannot buy. The free 10 s teaser (once per phone) and the ₪5 first full
video are website flows, not API flows.

## Hard rules

1. **Never spend credits without an explicit yes.** Before `shotto_create_video` or `shotto_create_edit`, tell the
   user exactly what will be charged ("20-second presenter video, 20 credits; your balance is 85") and wait for a
   clear confirmation in this conversation. A general "go ahead" earlier does not cover a new paid job.
2. **Show the full script before approving.** After creation the script is written automatically. Show the hook and
   every line to the user, verbatim, in Hebrew. Call `shotto_approve_video` only after the user explicitly approves it.
3. **Approval is final.** Once approved, filming starts and the video cannot be remade or refunded for taste, style
   or a word that sounds different. Only small wording edits are possible, and only before approval.
4. **Never retry a paid call.** If `shotto_create_video` / `shotto_create_edit` errors or times out, call
   `shotto_list_jobs` first to see whether the job exists. Never call create again automatically.
5. **No invented claims.** The brief contains only facts the user gave you: no made-up prices, discounts, cities,
   durations, reviews or results. The user is responsible for what the video says.
6. Check `shotto_balance` before proposing a paid job. If it is too low, send the user to https://www.shottoai.com.

## Video flow (MCP)

1. `shotto_balance` → know what the user can afford.
2. `shotto_presenters` (optionally `gender`) → show a few names/thumbnails, let the user pick. Skip for comics.
3. Build the brief with the user (see below). Pick the length. State the cost. **Get a yes.**
4. `shotto_create_video` → returns `id`, `credits_charged`.
5. Poll `shotto_video_status` every 20-30 s until `status = awaiting_approval` (usually under a minute).
6. **Show the script** (`script.hook` + `script.lines`). Ask: approve as is, or change a word?
7. `shotto_approve_video` with `id` (and optionally an edited `script` with the same number of lines).
8. Poll `shotto_video_status` every 30-60 s until `done` (about 5 / 7 / 9 minutes after approval for 10 / 20 / 30 s;
   `estimated_seconds` is given).
   `in_review` means Shotto's team checks it before release; keep polling. Deliver `video_url`.

## Edit flow (MCP)

1. Get each clip's size in bytes and duration (e.g. `ffprobe`). MP4 or MOV, up to 250 MB per clip, up to 6 clips,
   up to 180 s total.
2. Compute the cost: free seconds left (from `shotto_balance`) first, then 10 credits/minute. State it. **Get a yes.**
3. `shotto_upload_url` per clip → `curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "<upload_url>"`.
4. `shotto_create_edit` with `paths` (in order), `seconds` (total), optional `options`
   (`skin`: bold | clean | neon | comic; `captions`, `music`, `endcard`, `reframe`).
5. Poll `shotto_edit_status` until `done` → `video_url` (about 2 minutes + 1 per minute of footage). The same clip is never charged twice (`duplicate: true`).

## A brief that produces a good script

Required fields: `business_name`, `vertical` (clinic, fitness, food, realestate, education, ecommerce, home,
professional, other), `brief` (10-600 chars), `target_seconds`. Optional `quality`: `regular` (default, 1080x1920,
fine for reels and stories) or `hd` (sharper, double the credits); ask only if the user cares about sharpness.

The brief (Hebrew) should contain:
- the business name as it should be spoken;
- what they sell, and for whom;
- **one** concrete fact or offer (e.g. "שיעור ניסיון ראשון במתנה", "משלוח חינם מעל מאתיים שקל");
- numbers written in words, never digits;
- nothing the user did not say.

Good: `סטודיו פילאטיס מכשירים ברמת גן לנשים אחרי לידה. שיעור ניסיון ראשון במתנה.`
Bad: `best pilates studio, call now!!!` (English, no fact, no audience).

Length: **10 s** = one message (hook + 1 line, ~22 words) · **20 s** = default (hook + 3 lines, ~40 words) ·
**30 s** = a short story (same 3-line script, filmed as 3 takes). Pick 20 unless the user asks otherwise.

Optional: `tone` (friendly | energetic | calm | professional), `cta_type` (leads | whatsapp | website | call) with
`whatsapp` or `website`, `cta` (custom Hebrew sentence), `presenter_gender` (voice for comics).

## Errors

401 bad/missing key → ask the user to create one at /settings/api. 402 `NO_CREDITS` → tell the user to buy credits
at https://www.shottoai.com; do not retry. 409 `NOT_READY` → the script is not written yet, poll and try later;
409 `NOT_AWAITING` → already approved or expired, check status. 429 → wait `Retry-After` seconds (60 requests/min
per key; 3 edits per 10 minutes). Messages come back in Hebrew; translate them for the user if needed.