This API puts LumarLabs’s face and video models behind an HTTP call. You post an image, a clip or a live stream; you get back the same thing with a different face on it. Seven features, one key, nothing to install.

Two shapes of call. Most features are asynchronous: you submit a job, poll it, and collect a signed URL when it finishes. Full Live Swap is a session — you open it, stream through it, and close it, charged by the second you actually use.

Every call is authenticated with a bearer key and paid for from a balance you top up in advance. Nothing recurring, no floor to clear, and a failed job costs nothing.

Three steps to your first render: upload an asset, submit a job, poll for the result.

# 1 · Upload an asset → get a file_key
FILE_KEY=$(curl -s https://api.lumarlabs.ai/api/v1/uploads \
  -H "Authorization: Bearer $LUMARLABS_API_KEY" \
  -F "file=@base.png" | jq -r .file_key)

# 2 · Submit the job
JOB=$(curl -s https://api.lumarlabs.ai/api/v1/face-swap-image \
  -H "Authorization: Bearer $LUMARLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image_key\":\"$FILE_KEY\",\"face_key\":\"$FACE_KEY\"}")

# 3 · Poll the status_url the submit handed back
curl -s "https://api.lumarlabs.ai$(echo "$JOB" | jq -r .status_url)" \
  -H "Authorization: Bearer $LUMARLABS_API_KEY"

Send your key as a bearer token on every request.

Authorization: Bearer lmr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Capability calls reference inputs by file_key, not by URL. Upload each asset first and pass back the key you get. We host the upload — there is no CORS or presign dance, and no external URLs are fetched.

{
  "file_key": "api/images/9f8c…/base.png",
  "url": "https://…"
}

Images and audio up to 45 MB, video up to 500 MB.

Every capability except Full Live Swap is asynchronous: a submit returns immediately with an id, and you poll its status URL until it reaches a terminal state. Every submit answers with the same three fields, whichever capability it was:

{
  "id": "…",
  "status": "queued",
  "status_url": "/api/v1/jobs/…"
}

Poll status_url rather than assembling the path yourself — it is the one thing that stays correct if the route ever moves.

{
  "id": "…",
  "status": "queued | processing | succeeded | failed",
  "output_url": "https://…",
  "charged_usd": 0.06,
  "error": { "code": "face_not_detected", "message": "…" }
}

You are billed when a job completes. A job that fails is refunded in full — you are never charged for a result you did not get.

Rather than polling, pass a callback_urlwhen you submit and we'll POST you the result the moment the job reaches a terminal state. Available on every capability that returns a job.

-d '{"image_key":"…","face_key":"…","callback_url":"https://yourapp.com/hooks/lumarlabs"}'

The body carries the same object GET /v1/jobs/{id} returns, under data — so the handler you already wrote for polling can take this straight off the wire.

{
  "event": "job.succeeded",
  "sent_at": "2026-08-15T09:31:07Z",
  "delivery_id": "…",
  "data": {
    "id": "…",
    "status": "succeeded",
    "output_url": "https://…",
    "charged_usd": 0.06,
    "error": null
  }
}

event is job.succeeded or job.failed. Failures are delivered too — a render that did not work is exactly the thing your user is waiting on.

Verify every delivery

Each POST carries LumarLabs-Signature as t=<unix>,v1=<hex>. The hex is an HMAC-SHA256, keyed on your signing secret, over the string <t>.<raw body>. Sign the raw bytes — parsing and re-serialising the JSON first will not match.

import crypto from "node:crypto";

// express.raw() — NOT express.json(). The signature covers the bytes we sent.
app.post("/hooks/lumarlabs", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("LumarLabs-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));

  const expected = crypto
    .createHmac("sha256", process.env.LUMARLABS_WEBHOOK_SECRET)
    .update(parts.t + "." + req.body)
    .digest("hex");

  // Constant-time: a plain === leaks the answer one byte at a time.
  const ok =
    parts.v1 &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!ok) return res.sendStatus(400);

  // Reject anything older than five minutes so a captured delivery
  // cannot be replayed at you later.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return res.sendStatus(400);

  const { event, data } = JSON.parse(req.body);
  res.sendStatus(200);           // acknowledge first, work afterwards
  handleJob(event, data);
});

import hashlib, hmac, time

@app.post("/hooks/lumarlabs")
def lumarlabs_hook():
    header = request.headers.get("LumarLabs-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(","))

    expected = hmac.new(
        SECRET.encode(), f"{parts['t']}.".encode() + request.get_data(), hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, parts.get("v1", "")):
        return "", 400
    if abs(time.time() - int(parts["t"])) > 300:
        return "", 400

    payload = request.get_json()
    return "", 200

Your signing secret lives in the console under Billing. It is per-account, so it keeps working when you rotate an API key — rotate it separately if it is ever exposed.

Delivery, retries and duplicates

Send an Idempotency-Key header on any submit. A retry carrying the same key returns the original job — no second charge, no duplicate render. A network timeout costs you nothing.

-H "Idempotency-Key: your-own-unique-id"

60 requests per minute by default. Exceeding it returns 429 with code rate_limited.

Errors carry a stable code you can branch on and a message meant for a human. Branch on the code — the prose may change, the codes will not.

Put your character into a reference video, keeping its motion.

Swap a face into a video.

Swap a face into a single image.

curl https://api.lumarlabs.ai/api/v1/face-swap-image \
  -H "Authorization: Bearer $LUMARLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_key":"api/images/…","face_key":"api/images/…"}'

Animate a still character image to match a reference video’s motion.

A talking avatar from one portrait and a script.

Match a video’s mouth movement to your audio.

Real-time face swap over a live stream. Unlike the others this is a session, not a job: create one, connect over WebSocket, and stream.

{
  "session_id": "…",
  "stream_url": "wss://api.lumarlabs.ai/realtime",
  "session_token": "rt_…",
  "prompt": "…",
  "max_duration_sec": 600,
  "max_cost_usd": 25.00
}

prompt comes back resolved, so you can see the default you were given when you did not send one.

Real-time voice conversion. Like Full Live Swap this is a session rather than a job: open one, stream audio frames over the socket, and receive converted audio back on the same connection.

Pick a target voice first. The reference clip stays on our side — you never handle it.

[
  {
    "id": "8f2c…",
    "name": "Narrator",
    "description": "Warm, measured.",
    "preview_url": "https://…/preview.mp3"
  }
]

{
  "session_id": "…",
  "stream_url": "wss://api.lumarlabs.ai/realtime",
  "session_token": "rt_…",
  "max_duration_sec": 600,
  "max_cost_usd": 3.60
}

On connect we hand the engine your chosen voice, then send you one JSON frame with the audio format to use in both directions:

{ "sample_rate": 22050, "chunk_frames": 4096 }

After that it is audio both ways: send raw mono PCM (int16, little-endian, at the sample_rate above) as binary frames, and converted audio comes back in the same format. Send roughly chunk_frames per message — much smaller wastes round-trips, much larger adds latency.

Check your prepaid balance and spend from your own system.

{
  "balance_usd": 84.20,
  "total_spent_usd": 15.80,
  "total_topped_up_usd": 100.00,
  "spent_this_week_usd": 4.10,
  "spent_this_month_usd": 15.80,
  "spent_this_year_usd": 15.80
}

[
  {
    "id": "…",
    "endpoint": "face-swap-image",
    "feature": "face_swap_image",
    "status": "succeeded",
    "charged_usd": 0.06,
    "reason": null,
    "created_at": "2026-08-15T09:31:07Z"
  }
]

limit defaults to 100 and tops out at 500 — ask for more explicitly if you want more.

Use /usage/summary for totals — it is computed from your full history. The /usage log is capped, so summing it under-reports once you are busy.

Live rates, read from the API itself — this table cannot go stale. Public, no authentication required.