Quickstart

1. Get a key

Sign in at app.kolamlabs.ai. On the account page, create a key.

• Test keys (rk_test_…) are free. They run no check and return realistic sample verdicts, so you can build your integration before you spend anything.
• Live keys (rk_live_…) run real checks, paid from your account's prepaid credit.

Keys are shown once, so store them as secrets. You can give each key a monthly spend cap.

2. Check a take

Send the clip and, optionally, photos of each character as reference[NAME]. Repeat the field for several photos or several characters.

curl "https://api.kolamlabs.ai/v1/checks?wait=60" \
  -H "Authorization: Bearer $RACCORD_API_KEY" \
  -F clip=@take.mp4 \
  -F "reference[Maya]=@maya_front.jpg" \
  -F "reference[Maya]=@maya_side.jpg"

?wait=60 holds the request until the verdict is ready (up to 60 seconds). Without it, a live check returns 202 straight away with state: "queued"; poll GET /v1/checks/{id} or use a webhook. Test checks always finish at once with 200.

3. Read the answer

{
  "id": "chk_6f1c…",
  "state": "done",
  "verdict": "fail",
  "headline": "Don't use this take: 1 problem found.",
  "cost": {"usd": 0.04, "display": "$0.04"},
  "result": {
    "findings": [{
      "check": "identity",
      "severity": "fail",
      "title": "Maya's face changes from 0:02.5 to the end of the take and no longer matches the reference.",
      "fix": "Re-render this take with a different seed and Maya's reference images attached.",
      "start": 2.5, "end": 4.0, "confidence": 0.92
    }]
  },
  "report_url": "/v1/checks/chk_6f1c…/report"
}

• verdict is pass, fail or unsure.
• Each finding's title says what's wrong, fix says what to do, and start/end say when, in seconds.
• report_url is an HTML report with the frames as evidence. It's a path on the API, fetched with your key like any other call; on the review screen it opens without one. Test checks have no report (null).

The full shape is on Reading a verdict.

4. In Python

pip install raccord-sdk

from raccord_sdk import Raccord

raccord = Raccord()  # reads RACCORD_API_KEY
take = raccord.check("take.mp4", references={"Maya": ["refs/maya/"]})  # folders work too

if take.passed:
    publish("take.mp4")
else:
    for f in take.findings:
        print(f["title"], "→", f["fix"])

Every SDK call retries safely: it sends an Idempotency-Key, so a network retry never charges twice.

Test mode

With a test key, the file name chooses the sample, like test card numbers:

With references sent, the failing sample is an identity failure named for your first character, so you can build identity handling against a test key. Pre-flight fails when the prompt contains "fail". Test checks cost nothing and are marked "test": true in the signed record. Samples are real engine output on sample clips; only clip.sha256 is your file's.