Skip to contentvideo.me

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

  1. Create an API key on your Account page. It is shown once, so store it as a secret on your server.
  2. Add credits with a plan or a credit pack. API videos are paid from the same wallet as the studio.
  3. Create an avatar from a photo with a consent statement, or use one you made in the studio.
  4. Start a video, then check its status (or wait for the webhook) and download it.
Node.js: make a video and wait for 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.

API prices per tier
Tier (quality)Credits per 15 sFrom, per secondWhat you get
Standard
standard
3$0.029Natural lip-sync and expression. The best value for everyday social posts.
Premium
premium
9$0.086Studio-grade 1080p video with a natural voice. Calm, true-to-photo motion for launches, ads and client work.
Premium Expressive
expressive
18$0.171Our 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.

Create an avatar
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 from GET /api/v1/voices.
  • quality: standard, premium (default) or expressive.
  • aspect: 9:16 (default), 1:1 or 16: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.
  • title and captions (default true: an SRT captions file).
Start a video
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."
  }'
Answer (201)
{
  "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.

Check a video
curl https://your-video-me-site/api/v1/videos/5b0e… \
  -H "Authorization: Bearer $VIDEOME_API_KEY"
Answer when it is done
{
  "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 a prompt, with seconds and aspect. Add image to set the first frame.
  • motion, motion-hd: animate an image, which is one of your avatars ({"kind": "avatar", "id": …}) or one of your images ({"kind": "creation", "id": …}).
  • remix-edit: change a video from your library (2 to 10 seconds) with a prompt. remix-voice: give it a new script in one of your voices, with the lips re-synced.
  • vision, vision-pro: images from a prompt. Add image to edit one of yours.
  • voice: narration of a script in one voice. podcast: a script written as lines from two speakers ("Host: …", "Guest: …") with two voices.

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.

Make a clip
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" }.

Error codes
StatusMeaning
400The request is missing a field or has a wrong value. The message says which.
401The API key is missing, malformed or revoked.
402Not enough credits for this video. Buy a credit pack, then try again.
403The account is read-only, or that quality is not available.
404The avatar or video does not exist on this account.
409The request clashed with another one. Send it again.
413The photo is larger than 10 MB.
422The content was refused: a script too long for 60 seconds, an unverified avatar, or text the safety check blocked.
429You already have 5 videos rendering. Wait for one to finish.
5xxSomething 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.