Eve library

human-video-ts

Other

Revision 1

On this page

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 ifMatch as 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 ifMatch at 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