Kolam Labs
Menu

Endpoints

Base URL https://api.kolamlabs.ai. Every request sends Authorization: Bearer rk_live_… (or rk_test_…). Files go as multipart/form-data. Every POST accepts ?wait=SECONDS (values above 120 count as 120) and an Idempotency-Key header.

Fields shared by the checks:

Field Meaning
reference[NAME] A photo of character NAME. Repeat for more photos (two to five is best) or more characters. JPG, PNG, WebP. See Reference photos.
costume[NAME] A photo of NAME's costume for this scene (face and outfit visible). Needs reference[NAME] too.
size The delivery resolution, e.g. 1920x1080.
fps The delivery frame rate, e.g. 24.
label Your name for this check, shown on the review screen.

Video files: MP4, MOV, M4V, WebM, MKV or AVI, up to 2 GB. Images: up to 30 MB.

Check a take

POST /v1/checks. Field: clip (video).

curl "https://api.kolamlabs.ai/v1/checks?wait=60" -H "Authorization: Bearer $KEY" \
  -F clip=@take.mp4 -F "reference[Maya]=@maya.jpg" -F "costume[Maya]=@maya_sc12.jpg" -F size=1920x1080 -F fps=24

Priced per second of video.

Rank takes

POST /v1/rankings. Field: clips (two or more videos, repeat the field).

Takes that pass come first, then "not sure", then failures. Among clean takes, the one whose characters match their references most closely wins. result.top_two names up to two passing takes to use; it's empty when none passes, and headline then names the least bad. Priced per second of video, summed over the takes.

curl "https://api.kolamlabs.ai/v1/rankings?wait=120" -H "Authorization: Bearer $KEY" \
  -F clips=@take1.mp4 -F clips=@take2.mp4 -F clips=@take3.mp4 -F "reference[Maya]=@maya.jpg"

Check a start frame

POST /v1/keyframes. Field: image.

Check the still you're about to animate. It catches:

  • the wrong person or nobody matching
  • the wrong costume colour
  • a blank image
  • the wrong shape for the delivery (e.g. a square frame for a 16:9 delivery, which the model will crop or stretch)

It answers in about a quarter of a second, at a flat price per image.

Pre-flight a prompt

POST /v1/preflights. Fields: prompt (text), plus the reference and costume photos you'll render with. Send JSON instead ({"prompt": "…"}) when there are no photos.

It catches problems before anything is rendered:

  • a reference folder holding someone else's photo
  • photos with no usable face (none, too small, turned away, several faces)
  • two characters whose references look like the same person
  • a costume photo with no character reference
  • a character in the prompt with no references
  • the prompt's outfit colour contradicting the costume, or itself

Flat price per pre-flight.

Check an extension

POST /v1/extensions. Fields: previous (the segment so far), segment (the new extension).

It runs the full check on the new segment, plus the join with the one before:

  • the picture jumping instead of continuing
  • brightness or colour shifting
  • the face or outfit changing
  • a different size or frame rate

Pass means it's good to pay for the next extension. Priced per second of the new segment.

Preview a render in progress (early abort)

POST /v1/previews. Fields: frame (4–8 images decoded from the model's current guess of the finished video; repeat the field), progress (0 to 1: the share of denoising steps done).

result.stop is true only when the render is clearly doomed: the wrong person, the wrong costume colour, or a collapsed picture. A preview never passes a take; check the finished take as usual. Flat price per look. See Saving renders.

Read checks

  • GET /v1/checks/{id} gets a check. ?wait=SECONDS waits for it to finish.
  • GET /v1/checks?limit=20&before=2026-11-05T10:00:00Z lists checks, newest first, in the key's mode (mode=live or test to choose, with the review screen's session).
  • GET /v1/checks/{id}/report is the HTML report with evidence, fetched with your key. ?n=1 gives the second take's report in a ranking. Test checks have none.
  • POST /v1/checks/{id}/review takes {"review": "approved" | "rejected" | "escalated" | null}.

Account

  • GET /v1/usage: credit balance, this month's spend and seconds, prices, and, for a key, its cap and spend.
  • POST /v1/webhooks with {"url": "https://…"}, plus GET /v1/webhooks and DELETE /v1/webhooks/{id}. See Webhooks.
  • POST /v1/billing/checkout with {"pack": "pack_20"} returns {"url"}, the payment page for a credit pack.

Verification

  • GET /v1/signing-keys: public keys (no API key needed).
  • POST /v1/verify with {"record", "signature"}: checks a signed record.
  • POST /v1/checks/{id}/rerun: re-runs a check and compares. See Signed verdicts.