Not live yet Make videos from your own code with the API, or let an AI assistant like Claude make them over MCP. This page shows how both will work.
Quick start
From a screen recording to a finished video in three steps.
-
Create a key
Make one under API keys. It's shown once, so put it straight into your server's settings.
-
Send a recording
Post a link to your screen recording. Handtap finds your taps and films a real hand tapping your phone.
POST /v1/videos -
Get the video
Check on it until it's done, or add a webhook and we'll tell you. You get a link to the MP4.
GET /v1/videos/{id}
Make your first video
Start a video, then check on it until it's done. Each finished video uses 1 credit.
What you can send
The body of POST /videos, as JSON.
| Field | What it does |
|---|---|
recording_url | Required. A link we can download your screen recording from. |
device | "auto" (the default) or "hand". Both film a real hand tapping your phone as it lies on a bed or desk. The recording must be upright and have taps in it; one that is landscape or has no taps fails, and failed videos are free. |
hook_photo_url | Optional. A photo for the scene to copy: its bed or desk, its light, and the skin and nails of the hand. |
webhook_url | Optional. Where to send video.completed or video.failed for this video. |
Endpoints
All under https://api.handtap.ai/v1, with your key as a Bearer token.
| Endpoint | What it does |
|---|---|
POST /videos | Starts a video. Returns {id, status: "queued", credits: 1}; the credit is only used if it finishes. |
GET /videos/{id} | One video: status (queued, rendering, done or failed), progress, and video_url or error. |
GET /videos?limit=20 | Your latest videos, newest first. |
GET /credits | Your plan and credits: {plan, left, used}. |
Paste this into your coding agent
Gives Claude Code, Cursor or Codex what it needs to build with Handtap.
API keys
A key lets your code make videos with your credits.
| Name | Key | Created | Last used | Actions |
|---|---|---|---|---|
|
No keys yetCreate one to start making videos from your code.
| ||||
- Shown once. You see the whole key only when you make it. Copy it then; afterwards it shows as
ht_live_…and its last four characters. - Keep it on your server. Anyone with the key can spend your credits, so never put it in an app or a web page.
- Revoke anytime. A revoked key stops working straight away. Make a new one first if something still uses it.
Connect an AI assistant
Let Claude, ChatGPT, Cursor and other assistants make videos for you. There's no key: you sign in with your Handtap account the first time, and it uses your credits.
Remote server · Streamable HTTP · sign in with OAuth in your browser
Set it up
Pick where you'll use it.
Add Handtap to Claude on the web, desktop or phone, then ask it for a video in any chat.
Or add it yourself:
- In Claude, open Settings → Connectors.
- Choose Add custom connector, name it Handtap and paste the server URL.
- Choose Connect and sign in to Handtap in the window that opens.
Run this in your terminal:
Then type /mcp in Claude Code, choose handtap and sign in. Add --scope user to have it in every project.
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:
Cursor asks you to sign in to Handtap the first time it uses it.
- In ChatGPT, open Settings → Apps & Connectors.
- Under Advanced settings, turn on Developer mode if your plan asks for it, then choose Create.
- Name it Handtap, paste the server URL and choose OAuth.
- Sign in to Handtap, then pick Handtap from the tools menu in a chat.
- Add a remote MCP server with the server URL. Choose Streamable HTTP if your client asks for a transport.
- Leave the key empty: sign in with your Handtap account when your client asks.
Only takes local servers? Run it through mcp-remote:
Tools
What your assistant can do once Handtap is connected.
Makes a video from a recording link: a real hand tapping your phone, with an optional hook photo.
Checks a video's progress, and gives its link once it's done.
Your latest videos, newest first.
How many credits you have left this month.
Try asking
Paste one into your assistant once it's connected.
Webhooks
Get told when a video is done instead of checking on it. We send a POST to your address.
Check it came from us
Every webhook is signed, so nobody else can pretend a video is done.
Each endpoint gets its own signing secret when you add it. Every request carries a Handtap-Signature header: the HMAC-SHA256 of the raw request body, keyed with that secret and written in hex. Work it out yourself and compare before you trust the body.
Answer with any 2xx status to say you got it. If you don't, we try again up to 4 times, waiting longer each time. That means the same event can arrive twice, so use the video's id to skip repeats.
Example payload
The JSON body we send, one event per request.
This month
Videos made with a key or over MCP.
API videos this month
0
With a key or over MCP
Requests
0
Every call, this month
Credits left
–
Shared with the app
Limits
- Videos are made one at a time, in the order they arrive.
- 1 credit per finished video, whichever kind. Previews and failed videos are free.
- API and MCP videos use the same credits as the app.
API calls
The last 30 days.