Developers
The video.me API.
Create consent-checked talking videos from your own platform. Send a photo, a script and a voice, and get back a finished video, priced in credits before it starts.
Quick start
- Create an API key on your Account page. It is shown once, so store it as a secret on your server.
- Add credits with a plan or a credit pack. API videos are paid from the same wallet as the studio.
- Create an avatar from a photo with a consent statement, or use one you made in the studio.
- Start a video, then check its status (or wait for the webhook) and download it.
const BASE = "https://your-video-me-site/api/v1";
const headers = { Authorization: `Bearer ${process.env.VIDEOME_API_KEY}`, "Content-Type": "application/json" };
// 1. Start the video (credits are held now and refunded automatically if it fails).
const video = await fetch(`$https://your-video-me-site/videos`, {
method: "POST", headers,
body: JSON.stringify({ avatar_id, voice: "kore-en-us", quality: "premium", script }),
}).then((r) => r.json());
// 2. Check every 10 seconds until it is done (or listen for the video.completed webhook).
let status = video;
while (status.status === "queued" || status.status === "processing") {
await new Promise((r) => setTimeout(r, 10_000));
status = await fetch(`$https://your-video-me-site/videos/${video.id}`, { headers }).then((r) => r.json());
}
console.log(status.status, status.video_url);Authentication
Send your key in the Authorization header on every request: Authorization: Bearer vm_…. Keys belong to your account and spend its credits, so call the API from your server, never from a browser or a mobile app. Revoke a key on the Account page at any time.
The base address is this site followed by /api/v1. All bodies are JSON.
Pricing
Each video is priced in credits by its tier and length (rounded up to 15, 30, 45 or 60 seconds), and the credits are held when it starts. If the video fails, they come back automatically. GET /api/v1/models returns the same prices.
Tier (quality) | Credits per 15 s | From, per second | What you get |
|---|---|---|---|
Standardstandard | 3 | $0.029 | Natural lip-sync and expression. The best value for everyday social posts. |
Premiumpremium | 9 | $0.086 | Studio-grade 1080p video with a natural voice. Calm, true-to-photo motion for launches, ads and client work. |
Premium Expressiveexpressive | 18 | $0.171 | Our most lifelike 1080p video: more head movement, expression and energy, like a creator talking to camera. |
Dollar prices use the $50 pack of 350 credits. Premium and Premium Expressive switch to a backup engine automatically if the main one is unavailable, at the same price to you.
Avatars and consent
POST /api/v1/avatars creates an avatar from a JPEG, PNG or WebP portrait between 20 KB and 10 MB, sent as image_url (a public https link) or image_base64. GET /api/v1/avatars lists your avatars and their status.
Every avatar needs a consent statement, sent word for word in consent_statement. We keep it on record with the avatar. Use "consent": "self" when the photo shows you, or "consent": "platform" when it shows one of your users who agreed to it:
consent: "platform"
I confirm the person shown in this photo gave their consent for a talking AI avatar of them to be made, I keep a record of that consent, and neither I nor my users will use this avatar to mislead anyone or pretend to be another person.
consent: "self"
I confirm this photo shows me, that I am the person who appears in it, and that I will not use this avatar to mislead anyone or pretend to be another person.
The photo and name are checked right away. The answer's status is verified (ready to use), flagged (a person will review it, for example a name that looks like a public figure) or rejected (the notes say why). Never upload someone without their consent: misuse closes the account.
curl -X POST https://your-video-me-site/api/v1/avatars \
-H "Authorization: Bearer $VIDEOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Maya",
"image_url": "https://cdn.example.com/maya.jpg",
"consent": "platform",
"consent_statement": "<the platform statement below, word for word>"
}'Videos
POST /api/v1/videos starts a video and holds its credits.
avatar_id(required): a verified avatar on your account.script(required): 10 to 4,000 characters. At most about 156 words, the length of a 60-second video.voice(required): a voice id fromGET /api/v1/voices.quality:standard,premium(default) orexpressive.aspect:9:16(default),1:1or16:9. Premium tiers keep the shape of the photo, so send a photo in the shape you want.length_seconds: 15, 30, 45, 60. Leave it out and we pick the shortest length that fits the script.titleandcaptions(default true: an SRT captions file).
curl -X POST https://your-video-me-site/api/v1/videos \
-H "Authorization: Bearer $VIDEOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"avatar_id": "8c1f…",
"voice": "kore-en-us",
"quality": "premium",
"aspect": "9:16",
"script": "Hi! Three tips to film better videos on your phone."
}'{
"id": "5b0e…",
"status": "processing",
"quality": "premium",
"length_seconds": 15,
"credits": 10,
"video_url": null
}GET /api/v1/videos/{id} returns the status: queued, processing, completed or failed. A Premium video usually takes about two minutes. When it is completed, video_url (MP4) and captions_url are signed links that work for one hour: download the file to your own storage. Ask again for fresh links. Checking every 10 seconds is plenty. GET /api/v1/videos?limit=20 lists recent videos.
curl https://your-video-me-site/api/v1/videos/5b0e… \
-H "Authorization: Bearer $VIDEOME_API_KEY"{
"id": "5b0e…",
"status": "completed",
"duration_seconds": 14.6,
"credits": 10,
"credits_refunded": false,
"video_url": "https://…signed link, valid for 1 hour…",
"captions_url": "https://…/captions.srt",
"links_expire_at": "2026-11-19T18:05:00.000Z"
}Clips, images and voice
The Cinema, Motion, Remix, Vision and Voice engines share one endpoint. GET /api/v1/creations/models lists every model, what it needs and its starting price in credits.
cinema-lite,cinema-hd,cinema-pro: clips with sound from aprompt, withsecondsandaspect. Addimageto set the first frame.motion,motion-hd: animate animage, which is one of your avatars ({"kind": "avatar", "id": …}) or one of your images ({"kind": "creation", "id": …}).remix-edit: change avideofrom your library (2 to 10 seconds) with aprompt.remix-voice: give it a newscriptin one of yourvoices, with the lips re-synced.vision,vision-pro: images from aprompt. Addimageto edit one of yours.voice: narration of ascriptin one voice.podcast: ascriptwritten as lines from two speakers ("Host: …", "Guest: …") with twovoices.
POST /api/v1/creations starts one and holds its credits. Images and audio usually finish in the same call; clips take a minute or two. Check GET /api/v1/creations/{id} until status is completed, then download url, a signed link that works for an hour. Failed jobs are refunded.
curl -X POST https://your-video-me-site/api/v1/creations \
-H "Authorization: Bearer $VIDEOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cinema-hd",
"prompt": "Slow push-in on a neon street food stall at night, steam rising",
"seconds": 8,
"aspect": "9:16"
}'Voices
GET /api/v1/voices lists 17 voices in US, UK, Nigerian and Indian English, Spanish, Mexican Spanish, French, German, Brazilian Portuguese and Japanese, plus any voice you copied with My Voice in the studio (ids that start with custom:). Accent voices speak with their accent on Premium tiers; Standard uses a matching voice from the same country.
Webhooks
Add an https endpoint on your Account page and we send a signed POST for video.completed and video.failed. Each request carries X-Influencer-Event, X-Influencer-Delivery (the same on every retry, so you can drop duplicates) and X-Influencer-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of <t>.<raw body> with your endpoint's secret. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
Webhooks are sent while your account's videos are being checked, so keep a status check running for any video you are waiting on.
Errors and limits
Errors answer with an HTTP status and { "error": "a plain sentence" }.
| Status | Meaning |
|---|---|
400 | The request is missing a field or has a wrong value. The message says which. |
401 | The API key is missing, malformed or revoked. |
402 | Not enough credits for this video. Buy a credit pack, then try again. |
403 | The account is read-only, or that quality is not available. |
404 | The avatar or video does not exist on this account. |
409 | The request clashed with another one. Send it again. |
413 | The photo is larger than 10 MB. |
422 | The content was refused: a script too long for 60 seconds, an unverified avatar, or text the safety check blocked. |
429 | You already have 5 videos rendering. Wait for one to finish. |
5xx | Something failed on our side. Retry with a short wait. You are never charged for a video that fails. |
Up to 5 videos can render at once per account. Scripts go through the same safety check as the studio, and our safety policy applies to every API call.