The TypeScript client for the controlled human-video API (/v1/human-video).
client.ts is generated from the server's declared API surface and is not
edited by hand. A hand-written client is a consumer nobody wrote a contract for:
it drifts from the server a commit at a time, and the drift stays invisible
until somebody else's integration breaks.
- Surface:
apps/oshun/bff/src/generation/human-video-api-surface.ts - Generator:
apps/oshun/bff/src/generation/human-video-sdk-generator.ts - Drift guard: the generator's spec regenerates and compares against this file, so adding an endpoint without regenerating fails a test.
What the generated methods carry#
Three things the surface knows, which a naive client drops:
- Idempotency. Every mutation sends a key by default. A caller who forgets one pays for a second render on a timeout, and the key is bound to the request body, so a retry with a changed body is refused rather than silently replaying the first response.
- Preconditions in the type. A deciding method — approving, releasing,
correcting — takes
ifMatchas a required parameter. Not a runtime check: a client that discovers at runtime it needed an ETag has already made the call. - Retractions take no
ifMatchat all. Withdrawing a consent, withdrawing a release and deleting an asset are deliberately unguarded, so nobody can pass a stale ETag and have a takedown refused.
Two things worth reading before you integrate#
"Complete" is not "ready." The provider reporting completed means the
render finished — not that sync, exact speech or identity were checked. Those
run afterwards and some takes fail every one of them. Wait for a stage with a
decision in it: awaiting-review, releasable, cancelled, expired.
Cancelling a submitted render recovers nothing. There is no cancel endpoint
upstream; the render finishes on the provider's hardware and is billed. Cancel
stops us waiting and prevents release. That is why cancellation is its own verb
and there is no DELETE on a job.
Examples#
| Example | What it shows |
|---|---|
examples/exact-audio-active-scene.ts |
supply and approve the exact audio, then perform to it |
examples/multi-reference-cast.ts |
build a reference set and read its findings before spending |
examples/multi-speaker-dialogue.ts |
a two-hander with per-line speaker binding |
examples/polling-and-webhooks.ts |
poll with backoff; verify a webhook; treat the webhook as the fast path |
examples/shot-regeneration.ts |
preview what a regeneration invalidates, then accept the losses |