API

What this is, and what it is not

This is an API for renders. You send a brief; a language model drafts a scene — timed beats, named layers, motion tracks, a cue sheet — and our own renderer draws every frame from it. You get back an MP4 and, if you want it, the scene document that produced it.

It is not a gateway to the models behind it. There is no endpoint that returns a completion, and there is no parameter that lets you address a provider directly. That is a deliberate limit rather than an omission: we are permitted to sell you a clip, not access to the models we buy. If you want a raw model API, the providers sell one directly and you should buy it from them.

Getting a key

Sign up or sign in with your email and confirm the link in your inbox. No payment is required to create an account. Then open Credits & account and create a key under API keys. Keys are listed in GET /api/v1/account alongside your balance.

New and existing accounts use the same secure email-link flow. If your link does not arrive, check the delivery status shown in the form and your spam folder, or request a new link. Add prepaid credit when you are ready to generate, and review the price before submitting a render.

The key is shown once — only a hash is stored, so it cannot be recovered or re-displayed. If you lose it, revoke it and make another.

A key can spend the balance on the account that created it, and nothing else. It cannot create another key or start a session, which is what makes revoking a leaked key final rather than the start of a chase.

Authentication

Send the key as a bearer token. Keys begin cc_live_, which is what lets secret scanners recognise one if it is ever committed to a repository.

curl https://codedclips.com/api/v1/account \
  -H "Authorization: Bearer cc_live_..."

Prices

Credits are prepaid and shared with the studio. The packs are $5 → $5 of credit, $20 → $20 of credit, $50 → $50 of credit. The cheapest clip is 15¢; a recorded render costs more than that, because it is priced by its duration and by the model that drafts it. Price a brief before you submit it and you get the exact figure the render will charge.

The quote is a bound, not an estimate: output is priced at its ceiling and the render at the full duration you asked for, so a render cannot cost more than you were quoted. If a render fails, the charge is returned to your balance automatically — including when the host is killed mid-render, which is settled the next time the account is read.

Endpoints

POST /api/v1/quotes

Price a brief. Calls no provider and spends nothing.

curl https://codedclips.com/api/v1/quotes \
  -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a paper boat unfolding into a crane", "seconds": 6}'

Returns quotedCents, frames, seconds, fps and the model that would draft it.

POST /api/v1/renders

Accepts the same body, plus optional modelId and effort. Answers 202 with a job id and charges your balance immediately. Send the quote as confirmedCents to refuse a price change, and reuse a UUID requestIdwhen retrying the same submission to avoid a second render:

{
  "id": "0b0f1c2e-...",
  "status": "generating",
  "statusUrl": "https://codedclips.com/api/v1/renders/0b0f1c2e-...",
  "chargedCents": 62,
  "balanceCents": 5938,
  "seconds": 6,
  "fps": 24,
  "frames": 144
}

A render takes one to two minutes, so the request does not wait for it. Poll the id.

GET /api/v1/renders/{id}

The state of one render. done and failed are stated outright rather than left to be inferred from status. When the render is recorded, the response also carries absolute URLs: url for the MP4, shareUrl for a page anyone can watch, and sceneUrl for the scene document as Three.js.

# submit, then poll until done
ID=$(curl -s https://codedclips.com/api/v1/renders \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"a lighthouse in a storm","seconds":6}' | jq -r .id)

while true; do
  curl -s "https://codedclips.com/api/v1/renders/$ID" -H "Authorization: Bearer $KEY" | jq '.status'
  sleep 5
done

A render belonging to another account answers exactly as one that does not exist, so ids cannot be probed for existence, cost or timing.

GET /api/v1/account

Your balance, whether the account is frozen, and the keys on it with when each was last used. Useful as the first call when something is not working.

Errors

• 400 — the brief or the model is wrong. The body says which.
• 401 — the key is missing, malformed or revoked. The same answer for all three.
• 402 — not enough credit, or storage is due on a library you are not paying to hold. needsTopUp and neededCents say how much.
• 403 — the account is frozen while a payment dispute is resolved.
• 404 — no such render, or not yours.
• 429 — rate limited, or the lane is at capacity for the hour. Nothing is charged; the Retry-After header says when to try again.

Rate limits

Reads and submissions are counted separately, because a client that polls should not be spending the budget it needs to submit. Both are per key, and both are far above what a single integration needs. The limits that actually bound money are not these: they are your prepaid balance and a shared hourly ceiling on renders across the whole service, which is why a submission can be refused with 429 even when your own balance is healthy.

Storage

Recorded clips are stored, and storage accrues a small charge over time that is shown on the account. It is deliberately not a deletion policy: nothing is ever removed for non-payment, and an account’s balance is never driven negative. What happens instead is that an account which is not covering its storage cannot add to the library until it is — reversible, and it cannot destroy work you already have.

Questions

Write to support@codedclips.com. The Refunds and Terms pages apply to API usage exactly as they do to the studio.