Muvomi API

Every Muvomi studio tool, from your own code: generated video and motion graphics, talking avatars, pictures and designs, speech, voice cloning, dubbing, audio cleanup, transcription, background and object removal, and 3D models.

The base address is https://platform.muvomi.com/v1. Requests and answers are JSON (files are sent and fetched as they are). Work is paid with your Muvomi account's credits, the same as in the studio.

Quickstart

1. Sign in to the console and create a key under API keys. Keep it on your server.

2. Start work. Every operation answers at once with a job:

curl https://platform.muvomi.com/v1/images/generations \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A ceramic coffee cup on linen, soft morning light", "aspect_ratio": "4:5"}'

{ "id": "job_…", "object": "job", "operation": "image.generation", "status": "queued", … }

3. Follow the job until it has ended (or add a webhook), then fetch what it made:

curl https://platform.muvomi.com/v1/jobs/job_… -H "Authorization: Bearer $MUVOMI_API_KEY"

{ "status": "succeeded", "output": { "files": ["file_…"] }, "credits": 5, … }

curl -o picture.png https://platform.muvomi.com/v1/files/file_…/content -H "Authorization: Bearer $MUVOMI_API_KEY"

Authentication

Send your key in the Authorization header: Authorization: Bearer mvm_live_…. Keys are made and revoked in the console; each has:

• Scopes: what it may do. video, design, voice, 3d for each studio's operations, files for uploads and downloads, account for the balance and usage.
• A monthly credit limit, after which it is refused until the next month (UTC).
• Allowed addresses (IPs or CIDR ranges) it may be used from.
• An end date.

The API is for servers. It sends no CORS headers, so a web page can't call it: never put a key in a browser or an app people download.

Jobs

Every operation starts a job and answers 202 with it. A job is queued, running, then succeeded, failed or canceled.

{
  "id": "job_8sKq…",
  "object": "job",
  "operation": "video.generation",
  "status": "succeeded",
  "progress": 1,
  "output": { "files": ["file_…"] },
  "error": null,
  "credits": 25,
  "created_at": "2026-11-15T10:00:00.000Z",
  "finished_at": "2026-11-15T10:01:12.000Z"
}

• GET /v1/jobs/{id}: one job, as it is now. Ask every few seconds; a webhook is better.
• GET /v1/jobs?limit=20&status=succeeded&before=<created_at>: your jobs, newest first.
• POST /v1/jobs/{id}/cancel: stops a job whose operation can be stopped.

credits is what the job cost. A job that fails costs nothing: anything charged is given back.

Files

Pictures, videos and recordings you give an operation are uploaded first, and what operations make are files too. A file is file_ and 32 hex digits. Files you upload are also in your studio's Assets.

# Upload (up to 100 MB): the file itself as the body…
curl https://platform.muvomi.com/v1/files?name=interview.mp4 \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: video/mp4" --data-binary @interview.mp4

# …or as a form with a "file" field
curl https://platform.muvomi.com/v1/files -H "Authorization: Bearer $MUVOMI_API_KEY" -F file=@photo.jpg

{ "id": "file_…", "object": "file", "name": "photo.jpg", "kind": "image", "content_type": "image/png", "bytes": 482113, "width": 1600, "height": 2000, … }

• Pictures: PNG, JPEG, WebP, GIF, HEIC (kept as PNG). Videos: MP4, WebM, up to 10 minutes and 4K. Recordings: WAV, MP3, M4A, OGG, FLAC, AAC (kept as WAV).
• GET /v1/files/{id}: what it is. GET /v1/files/{id}/content: the file (ranges supported; ?download=1 to save it). DELETE /v1/files/{id}: deletes it, in the studio too.
• On the Free plan, pictures and videos come with Muvomi's watermark, as in the studio. Bought credits remove it.

Webhooks

Add an HTTPS endpoint in the console and Muvomi POSTs to it when a job ends: job.succeeded, job.failed, job.canceled. The body is an event whose data is the job. Answer with any 2xx within 10 seconds; anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours. An endpoint that fails 50 times in a row is turned off until you turn it on again.

Check every message: the Muvomi-Signature header is t=<unix seconds>,v1=<hex HMAC-SHA256> of <t>.<raw body>, with your endpoint's secret. Refuse messages older than five minutes.

// Node.js
import crypto from "node:crypto";

export function verified(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return age < 300 && parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

# Python
import hmac, hashlib, time

def verified(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(parts.get("v1", ""), expected)

Errors

A refusal has a status and a body that says why. request_id is in the body and in the X-Request-Id header: give it when you ask for help.

{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "…", "credits_needed": 25, "credits_available": 10, "request_id": "req_…" } }

Rate limits

• 300 requests a minute for each key; X-RateLimit-Limit and X-RateLimit-Remaining say where you are.
• 60 jobs started (and uploads) a minute, and 20 jobs running at once, for each account.
• Over a limit: 429 with Retry-After.

Idempotency

Send an Idempotency-Key header (any unique text up to 255 characters, a UUID is ideal) with every POST that starts work. Sent again with the same body, the same job is answered and nothing runs or is charged twice; with another body, 409. Keys are remembered for the life of the job.

Security

• HTTPS only, with HSTS. Keys are kept as one-way hashes and shown once.
• Every change to your API access (keys, webhooks, sign-ins) is in the console's audit trail.
• The console has no password of its own: you sign in with your Muvomi account, two-step verification included.
• Webhooks go only to public HTTPS addresses, and are signed.
• Your files and work are your account's alone: no key reaches another account's.

Prices

In credits, the same as the studio's; also at GET /v1/prices. Credits are bought in the console under Credits.

Account, usage, voices and avatars

• GET /v1/account (scope account): your credits and plan.
• GET /v1/usage?days=30 (account): jobs and credits by operation and by day.
• GET /v1/prices, GET /v1/operations: the price list and every operation with its input schema.
• GET /v1/voices (voice): the studio's voices and your own. DELETE /v1/voices/{id} removes one of your own.
• GET /v1/avatars, POST /v1/avatars, DELETE /v1/avatars/{id} (video): your avatars, for talking avatar videos. Making one takes name, image (a file id of a face picture, at least 256 pixels on its shorter side), an optional voice, and consent: true: “This is my own face, or I have this person's permission to make videos of them speaking.”

Video Studio

curl https://platform.muvomi.com/v1/videos/generations \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "muvomi-video",
  "prompt": "A slow dolly shot through a sunlit greenhouse, dust in the light",
  "duration": 5,
  "aspect_ratio": "16:9"
}'

curl https://platform.muvomi.com/v1/videos/motion \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "A bold launch title for a coffee brand, warm colours, type that builds word by word",
  "duration": 8
}'

curl https://platform.muvomi.com/v1/videos/avatar \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "avatar": "avatar_…",
  "script": "Hi! Here is what is new in our spring collection.",
  "voice": "voice_…",
  "style": "studio"
}'

curl https://platform.muvomi.com/v1/videos/background-removal \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "subject": "person"
}'

curl https://platform.muvomi.com/v1/videos/object-removal \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "what": "the microphone",
  "start": 0,
  "end": 8
}'

curl https://platform.muvomi.com/v1/videos/stabilize \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "action": "stabilize"
}'

curl https://platform.muvomi.com/v1/videos/dubbing \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "to": "es",
  "from": "auto",
  "rights": true
}'

Design Studio

curl https://platform.muvomi.com/v1/images/generations \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "A ceramic coffee cup on a linen tablecloth, soft morning light, product photo",
  "aspect_ratio": "4:5",
  "size": "2K"
}'

curl https://platform.muvomi.com/v1/images/edits \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Replace the background with a clean white studio sweep",
  "images": [
    "file_…"
  ]
}'

curl https://platform.muvomi.com/v1/designs \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Grand opening poster for a Lebanese bakery, Saturday 10am, warm and hand-made",
  "width": 1080,
  "height": 1350
}'

Voice Studio

curl https://platform.muvomi.com/v1/audio/speech \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "Welcome to Muvomi. Make something people remember.",
  "voice": "voice_…"
}'

curl https://platform.muvomi.com/v1/audio/clean \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "tool": "noise_removal",
  "strength": "strong"
}'

curl https://platform.muvomi.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…"
}'

curl https://platform.muvomi.com/v1/voices \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "file": "file_…",
  "name": "My voice",
  "tier": "instant",
  "consent": true
}'

3D Studio

curl https://platform.muvomi.com/v1/3d/models \
  -H "Authorization: Bearer $MUVOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "image": "file_…",
  "texture": true
}'