Eve library

V1 migration guide

Guide

Revision 1

On this page

Phase 182, 182.C.39.08. For callers of the existing avatar, voice and image-to-video flows — and for Veritas callers, whose surface is deferred.

The one-sentence version#

Migrating is not a rename, because the new flow makes promises the old one never made, and those promises need inputs the old request does not carry.

What the old flows actually guarantee#

Flow Exact dialogue Measured sync Identity bound to an authorization
text-to-video no no no
image-to-video no no no
human-video-exact-dialogue yes yes yes

The legacy flows are not broken and they are not being switched off. They have never had an exact-dialogue guarantee; what changed is that we now know what that guarantee would require, so continuing to ship them silently would be a different thing than shipping them before we knew (human-video-legacy-flows.ts).

Two consequences you will see in reporting before you see them anywhere else:

  • A flow that does not measure speech is not a flow that failed the gate. Those are opposite findings and one word covers both. Legacy jobs report not-applicable, and that word appears nowhere near passed — reporting them as failures fills a dashboard with red nobody can act on; reporting them as passes claims a measurement nobody made.
  • A legacy job that routes through a lane with a lip-sync model does not acquire the guarantee. It produces a mouth that matches something, nobody measured what, and a customer reasonably concludes the words are theirs. Reporting a sync or speech verdict on a flow that never had one is refused.

What you must supply to move#

Moving from You must add
text-to-video an approved script; an authorization for the person depicted
image-to-video an approved script; an authorization for the person in the image; the reference role the image plays

There is no one-click upgrade, and the reason is not ergonomic: a system that offers one produces jobs whose authorization was invented at the moment of the click. "Upgrade this job" is a different request with inputs the caller has to supply.

This is the part that surprises integrators, so it is the part to plan around.

referenceImage: 'https://cdn/seed.png' says nothing about role, nothing about whose face it is, and nothing about whether anybody agreed. The new contract makes an identity reference without an authorization a parse error, on purpose. So a stored reference has exactly two honest destinations (human-video-reference-migration.ts):

  1. first-frame — which requires no authorization and is a faithful translation of what the old image-to-video path did with the string: seed the first rendered frame.
  2. Refuse, and ask the owner what the image is.

Never identity. Upgrading the field into an identity reference means synthesising an authorization nobody gave — the exact thing this phase exists to prevent, arrived at through a data migration instead of a decision.

So the migration plan for a library of existing references is a people plan, not a data plan: every subject whose likeness you intend to keep using has to enrol, and enrolment binds an authorization to the digests of specific files. Budget for that first; it is the long pole and no amount of engineering shortens it.

Order of work#

  1. Inventory stored referenceImage values; map the ones you know to be non-identity to first-frame, and set the rest aside.
  2. Re-enrol subjects for the set aside, with proof (182.C.26.02), which produces authorizations bound to file digests.
  3. Lock scripts for the calls that need exact words; anything that does not can stay on a legacy flow indefinitely.
  4. Approve the audio those scripts will be measured against.
  5. Move call sites, and expect new refusals — hv.consent.missing (403) is the first one most integrations meet. See api-guide.md.

Veritas callers#

Not yet, and this guide will not pretend otherwise. Veritas and Metis are deferred to V1.2: their domain services, adapters and route handlers stay registered, and the member-facing surface returns a 404 carrying a machine-readable deferral reason rather than data a client has no route to render (apps/oshun/bff/src/middleware/release-scope.ts). Operator, admin and studio paths are deliberately exempt, because governance still reviews Veritas retraction queues while the room is hidden.

Two phase-182 items are gated on that release and remain open: 182.C.13.02 (wire the Veritas unified provider deliberately or retire it — do not leave unreachable HeyGen/Tavus/D-ID adapters presented as runtime capabilities) and 182.C.31.07 (consolidate the Veritas surface). Until one of those closes, there is no Veritas migration path to document, and writing one would describe a surface a caller cannot reach.

What this guide does not do#

It does not give you a code sample against a running server: nothing in this phase is mounted, and api-guide.md explains how to tell a captured response from a schema-derived one.