Yapflip API

Before you start

• Create an API key on the API page of your dashboard. Any account can use the API, individual or company.
• Dubs made through the API are billed like dubs from the dashboard: from your prepaid balance, or from your company plan if you're on Yapflip Business, with the same prices, monthly limit and dubs at a time.
• The base URL is https://yapflip.com/api/v1. Send JSON with Content-Type: application/json, except for file parts, which are raw bytes.

Files can be up to 4 GB and 2 hours long. Voice samples up to 50 MB.

Authentication

Send your key in the Authorization header on every request. Keys start with yf_live_. A missing, wrong or revoked key gets HTTP 401 with the code invalid_api_key.

Authorization: Bearer yf_live_...

Dub a file, step by step

1. Create the dub with the file name and size. You get the number of parts and the part size.
2. Upload each part with PUT, in order or in parallel. Parts are raw bytes, up to part_size each (the last one can be smaller).
3. Complete the upload. We check the file and return the dub as ready, with its length in seconds.
4. Start the dub with the languages, a voice and the files you want back. We charge it now and return HTTP 202.
5. Wait for the dub.done webhook, or check the dub every 10 to 30 seconds. Then download the files.

export YAPFLIP_KEY="yf_live_..."
API="https://yapflip.com/api/v1"

# 1. Create the dub and open the upload
curl -s "$API/dubs" -H "Authorization: Bearer $YAPFLIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "intro.mp4", "size_bytes": 52428800}'
# Answer: { "dub": { "id": "DUB_ID", "status": "uploading", ... },
#           "upload": { "parts": 1, "part_size": 94371840, ... } }

# 2. Upload the parts (split with the part_size you got)
split -b 94371840 -d -a 3 intro.mp4 part_
n=1
for p in part_*; do
  curl -s -X PUT "$API/dubs/DUB_ID/source/parts/$n" \
    -H "Authorization: Bearer $YAPFLIP_KEY" --data-binary @"$p"
  n=$((n + 1))
done

# 3. Complete the upload
curl -s -X POST "$API/dubs/DUB_ID/source/complete" -H "Authorization: Bearer $YAPFLIP_KEY"

# 4. Start the dub (voice ids come from GET /voices)
curl -s "$API/dubs/DUB_ID/start" -H "Authorization: Bearer $YAPFLIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_language": "en", "target_language": "es", "target_dialect": "es-MX",
       "voice": {"type": "library", "id": "VOICE_ID"}, "outputs": ["audio", "srt"]}'

# 5. Check the status, then download
curl -s "$API/dubs/DUB_ID" -H "Authorization: Bearer $YAPFLIP_KEY"
curl -s -o intro-es.m4a "$API/dubs/DUB_ID/files/audio" -H "Authorization: Bearer $YAPFLIP_KEY"

import os, time, requests

API = "https://yapflip.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['YAPFLIP_KEY']}"}

def check(r):
    if not r.ok:
        e = r.json()
        raise RuntimeError(f"{r.status_code} {e.get('code')}: {e.get('error')}")
    return r.json()

path = "intro.mp4"
r = check(requests.post(f"https://yapflip.com/api/v1/dubs", headers=H,
                        json={"filename": "intro.mp4", "size_bytes": os.path.getsize(path)}))
dub, up = r["dub"]["id"], r["upload"]

with open(path, "rb") as fh:
    for n in range(1, up["parts"] + 1):
        check(requests.put(f"https://yapflip.com/api/v1/dubs/{dub}/source/parts/{n}", headers=H, data=fh.read(up["part_size"])))
check(requests.post(f"https://yapflip.com/api/v1/dubs/{dub}/source/complete", headers=H))

check(requests.post(f"https://yapflip.com/api/v1/dubs/{dub}/start", headers=H, json={
    "source_language": "en", "target_language": "es",
    "voice": {"type": "library", "id": "VOICE_ID"}, "outputs": ["audio", "srt"],
}))

while True:  # or wait for the dub.done webhook
    d = check(requests.get(f"https://yapflip.com/api/v1/dubs/{dub}", headers=H))
    if d["status"] in ("done", "failed", "canceled"):
        break
    time.sleep(15)

if d["status"] == "done":
    with requests.get(f"https://yapflip.com/api/v1/dubs/{dub}/files/audio", headers=H, stream=True) as f, open("intro-es.m4a", "wb") as out:
        for chunk in f.iter_content(1 << 20):
            out.write(chunk)

// Node.js 18 or newer (built-in fetch)
import { open, stat } from "node:fs/promises";

const API = "https://yapflip.com/api/v1";
const H = { Authorization: `Bearer ${process.env.YAPFLIP_KEY}` };

async function call(method, path, body) {
  const r = await fetch(API + path, {
    method,
    headers: body ? { ...H, "Content-Type": "application/json" } : H,
    body: body ? JSON.stringify(body) : undefined,
  });
  const d = await r.json();
  if (!r.ok) throw new Error(`${r.status} ${d.code}: ${d.error}`);
  return d;
}

const path = "intro.mp4";
const { dub, upload } = await call("POST", "/dubs", { filename: "intro.mp4", size_bytes: (await stat(path)).size });

const file = await open(path);
for (let n = 1; n <= upload.parts; n++) {
  const buf = Buffer.alloc(upload.part_size);
  const { bytesRead } = await file.read(buf, 0, upload.part_size, (n - 1) * upload.part_size);
  const r = await fetch(`$https://yapflip.com/api/v1/dubs/${dub.id}/source/parts/${n}`, { method: "PUT", headers: H, body: buf.subarray(0, bytesRead) });
  if (!r.ok) throw new Error(`part ${n}: ${r.status}`);
}
await file.close();
await call("POST", `/dubs/${dub.id}/source/complete`);

await call("POST", `/dubs/${dub.id}/start`, {
  source_language: "en", target_language: "es",
  voice: { type: "library", id: "VOICE_ID" }, outputs: ["audio", "srt"],
});

let d;
do {
  await new Promise((ok) => setTimeout(ok, 15_000)); // or wait for the dub.done webhook
  d = await call("GET", `/dubs/${dub.id}`);
} while (!["done", "failed", "canceled"].includes(d.status));

Fields for starting a dub

source_language, target_language

Language codes from GET /voices (any to any).

voice

{ "type": "library", "id": "<voice id>" } or { "type": "own" } after uploading a voice sample with consent.

target_dialect

Optional regional style for some languages, like es-MX or pt-BR (GET /voices lists them).

outputs

Files to get back: audio, video (only if the file has video), voice, srt, docx. Default: audio and srt.

glossary

Optional list of up to 200 words: { term, say_as, translate }. Use it for names and brands.

review

true to stop after the script is written, so you can check it (GET and PATCH /script) and then confirm or discard it. The dub is charged when it starts; discarding the script or letting it expire does not refund the charge. Not available when less than 3 hours are left before the upload is deleted (24 hours after it started): you get 400 review_too_late.

subtitles

Optional { source, target } with your own SRT text instead of our transcription.

expected_charge_micros

Optional. If the price is different (for example, free minutes ran out), we answer 409 price_changed instead of charging it.

start_now

Required as true for individual accounts in the EU, EEA and UK: the customer asks to start right away and loses the right to withdraw from that dub.

Dub status

status is one of uploading, ready, queued, running, script_ready, done, failed or canceled. A company dub that is waiting for a free slot is queued with waiting_for_slot: true. When it's done, files lists what you can download; files are deleted after 30 days (files_expire_at). If a dub fails or we cancel it on our side, the charge goes back automatically (refunded: true). A script that you discard or don't confirm in time is not refunded: refunded stays false and script_end says discarded or expired.

Amounts are in micro-dollars: 1,000,000 = USD 1. charge_micros is what this dub cost.

Files

Download with GET /dubs/{id}/files/{kind}, where kind is audio, video, voice, srt_source, srt_target or docx. Range requests work, so you can resume large downloads.

Your own voice and consent

To dub with a person's own voice, you need their written consent, the same as in the dashboard. Before uploading the sample, send the consent version and the exact text the voice owner accepted. We store both as proof, with the date, IP address and API key. Without it, we don't accept the sample.

curl -s "$API/dubs/DUB_ID/voice" -H "Authorization: Bearer $YAPFLIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "my-voice.m4a", "size_bytes": 480000,
       "consent": {"subject": "self", "version": "own-voice-2026-10-30",
                   "text": "<the exact text below>"}}'
# Then PUT /dubs/DUB_ID/voice/parts/1 and POST /dubs/DUB_ID/voice/complete,
# and start the dub with "voice": {"type": "own"}.

Show the consent in a language the voice owner understands. Each of our 10 languages has its own version of the same text: own-voice-2026-10-30, own-voice-2026-10-30-es and own-voice-2026-10-30-ja, and so on. Send the version of the language you showed, with its text. We compare the text exactly, except for spaces and line breaks.

Current consent texts

Show this text to the voice owner and record their acceptance in your system before calling the API. When we update the text, the versions change and older versions get 409 consent_outdated.

Word fixes

If a done dub says a name or a word wrong, send changes as { from, to }. The first round, up to 10 changes, is free. Later changes cost 8¢ each, billed like the dub. We redo only the sentences that change.

curl -s "$API/dubs/DUB_ID/fixes" -H "Authorization: Bearer $YAPFLIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changes": [{"from": "Yap flip", "to": "Yapflip"}]}'

Script review

Start a dub with review: true and it stops at script_ready. Read the script with GET /dubs/{id}/script, fix sentences with PATCH (send the revision you read), then POST /script/confirm to record the voice, or /script/discard to cancel the dub (discarding does not refund the charge). If you don't confirm within 24 hours of the upload, the dub ends as failed and the charge is not refunded either. Fixing the script is free, and each dub includes one free round of word fixes after it's done.

Deleting

DELETE /dubs/{id} discards a dub that hasn't started, cancels one waiting for a slot (the charge goes back), discards a script waiting for review (no refund), or deletes the files of a finished dub right away. A dub that is running can be deleted when it's done.

Webhooks

Set a URL on the API page of your dashboard. We send a POST request with a JSON body, usually within two minutes, when a dub is done (dub.done), fails (dub.failed) or has a script ready to review (dub.script_ready). The event is short: read the dub with GET /dubs/{id} for the details.

POST /your/webhook HTTP/1.1
Content-Type: application/json
Yapflip-Event: dub.done
Yapflip-Delivery: 6f1c0d7e-1b7e-4a53-9d55-0f6c2b8f1a2e
Yapflip-Signature: t=1793385600,v1=5d41402abc4b2a76b9719d911017c592...

{"id": "6f1c0d7e-1b7e-4a53-9d55-0f6c2b8f1a2e", "type": "dub.done",
 "created_at": "2026-10-30T18:00:00.000Z",
 "data": {"dub": {"id": "DUB_ID", "status": "done", "title": "intro"}}}

Answer with any 2xx status within 10 seconds. Otherwise we retry after 1, 5, 30, 120, 360, 720 and 1,440 minutes. Use the Yapflip-Delivery header to ignore repeats. Test events from the dashboard aren't retried.

Checking the signature

Every request has a Yapflip-Signature header: t=<unix time>,v1=<signature>. The signature is the HMAC-SHA256 of "<t>.<raw body>" with your signing secret, in hex. Compute it over the raw body, compare in constant time, and reject requests older than 5 minutes.

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(",").map((x) => x.split("=")));
  if (!/^\d+$/.test(p.t ?? "") || Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${p.t}.${rawBody}`).digest();
  const got = Buffer.from(p.v1 ?? "", "hex");
  return got.length === expected.length && timingSafeEqual(got, expected);
}

Rate limits

Each key can make 60 requests a minute, and each account 300, counting every request including file parts. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit you get HTTP 429 with a Retry-After header.

Errors

Errors use HTTP status codes and a JSON body with error (a message you can show to a person) and, when it helps, code (stable, for your program) and fields.

{ "error": "You don't have enough balance for this dub. Add balance and try again.", "code": "insufficient_balance" }

All endpoints

https://yapflip.com/api/v1

• GET/accountWho is billed (balance or company plan), prices and limits.
• GET/voicesLanguages, library voices and regional styles.
• GET/dubsYour dubs, newest first. limit (up to 100) and before (next_before from the last page, an opaque cursor).
• POST/dubsCreate a dub and open the upload: { filename, size_bytes }.
• PUT/dubs/{id}/source/parts/{n}Upload part n of the file (raw bytes).
• POST/dubs/{id}/source/completeFinish the upload and check the file.
• POST/dubs/{id}/voiceOwn voice: consent and open the sample upload.
• PUT/dubs/{id}/voice/parts/{n}Upload part n of the voice sample.
• POST/dubs/{id}/voice/completeFinish the voice sample (10 seconds to 5 minutes of speech).
• POST/dubs/{id}/startCharge and start the dub.
• GET/dubs/{id}Status, progress, charge, files and fixes.
• GET/dubs/{id}/files/{kind}Download a file.
• POST/dubs/{id}/fixesFix words in a done dub.
• GET/dubs/{id}/scriptRead the script.
• PATCH/dubs/{id}/scriptFix sentences in the script.
• POST/dubs/{id}/script/confirmApprove the script and record the voice.
• POST/dubs/{id}/script/discardDiscard the script and cancel the dub (discarding does not refund the charge).
• DELETE/dubs/{id}Discard, cancel or delete files.

Questions about the API: [email protected].