realtime-avatar 0.5.0 → 0.5.2

package/README.md

@@ -70,20 +70,34 @@ all), and the `video` policy types are deliberately not one-to-one with the wire
 ```ts
 // calls
 rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, transcript?, metadata? })
-rta.endCall(sessionId, { reason? })    // free an abandoned call's slot now; idempotent, never throws
+rta.endCall(sessionId, { reason? })     // free an abandoned call's slot; idempotent, never throws
 
 // avatars
-rta.createAvatarFromVideo({ displayName, videoUrl, voice? })
+rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? })  // the only lane
+rta.createAvatarFromVideo({ displayName, videoUrl, voice? })                 // DEPRECATED — closed, 422
 rta.listAvatars()
 rta.getAvatar(avatarId)
-rta.syncClips(avatarId, clipUrls)      // after ANY clip change
+rta.updateAvatar(avatarId, patch)       // re-point displayName / defaultVoiceId
+rta.swapSource(avatarId, { sourceAssetId, anchorTimeMs? })  // re-shoot her: new loop, library re-renders
+rta.retimeAnchor(avatarId, anchorTimeMs)                    // same loop, different rest frame
+rta.deleteAvatar(avatarId)
+
+// clip library — declared as JSON, never as URLs
+rta.setClipLibrary(avatarId, { clips, expectedRevision? })  // declare the FULL set; CAS via expectedRevision
+rta.setLoop(avatarId, { motionPrompt })     // re-direct the RESTING LOOP; clips untouched
+rta.waitForLoop(avatarId)               // block until it settles; THROWS if it failed
+rta.waitForClips(avatarId)              // block until nothing is still rendering
+rta.listClips(avatarId)                 // rows + revision, anchor, eligibility
+rta.syncClips(avatarId, clipUrls)       // DEPRECATED — external-URL tier; use setClipLibrary
 
 // assets
 rta.createRemoteAsset({ kind, remoteUrl })
 rta.uploadAsset(file, { kind })
 
 // billing
-rta.creditBalance()
+rta.creditBalance()                                 // balance + reserved
+rta.listSessions({ from, to, endUserId })           // per-session: when, how long, what it cost
+rta.iterateSessions({ from, to })                   // the same, paging handled
 
 // webhooks
 verifyTranscript(rawBytes, headers, secret)

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-B45GgjrV.js';
-import './types-DLxz6uFE.js';
+import { P as ProxyConfig } from './types-CHrhuhYb.js';
+import './types-BeGuvyra.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * Register a character from a looping clip you host.
    *
-   * Use a VIDEO source for anything that will be called live. An avatar built from a still
-   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-   * track dimensions both look fine, only the pixels are wrong. Image sources are for
-   * offline lipsync renders.
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
    */
   async createAvatarFromVideo(input) {
     const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       metadata: input.metadata
     });
   }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
   async createAvatar(input) {
     const body = {
       displayName: input.displayName,
       sourceKind: input.sourceKind,
       sourceAssetId: input.sourceAssetId
     };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
     if (input.voice !== void 0) body.voice = input.voice;
     if (input.settings !== void 0) body.settings = input.settings;
     if (input.metadata !== void 0) body.metadata = input.metadata;
@@ -191,7 +225,14 @@ var RealtimeAvatar = class {
   async getAvatar(avatarId) {
     return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
   }
-  /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
   async updateAvatar(avatarId, patch) {
     return toAvatar(
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
@@ -274,6 +315,94 @@ var RealtimeAvatar = class {
       )
     );
   }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
   /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
   async listClips(avatarId) {
     return this.#clipEnvelope(
@@ -475,7 +604,13 @@ function toAvatar(raw) {
     sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
     // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
     // and serving, and this says why the re-shoot did not take.
-    error: a.error ? String(a.error) : null
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
   };
 }
 function toAsset(raw) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-B45GgjrV.js';
-import './types-DLxz6uFE.js';
+import { P as ProxyConfig } from './types-CHrhuhYb.js';
+import './types-BeGuvyra.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * Register a character from a looping clip you host.
    *
-   * Use a VIDEO source for anything that will be called live. An avatar built from a still
-   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-   * track dimensions both look fine, only the pixels are wrong. Image sources are for
-   * offline lipsync renders.
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
    */
   async createAvatarFromVideo(input) {
     const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       metadata: input.metadata
     });
   }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
   async createAvatar(input) {
     const body = {
       displayName: input.displayName,
       sourceKind: input.sourceKind,
       sourceAssetId: input.sourceAssetId
     };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
     if (input.voice !== void 0) body.voice = input.voice;
     if (input.settings !== void 0) body.settings = input.settings;
     if (input.metadata !== void 0) body.metadata = input.metadata;
@@ -191,7 +225,14 @@ var RealtimeAvatar = class {
   async getAvatar(avatarId) {
     return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
   }
-  /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
   async updateAvatar(avatarId, patch) {
     return toAvatar(
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
@@ -274,6 +315,94 @@ var RealtimeAvatar = class {
       )
     );
   }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
   /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
   async listClips(avatarId) {
     return this.#clipEnvelope(
@@ -475,7 +604,13 @@ function toAvatar(raw) {
     sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
     // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
     // and serving, and this says why the re-shoot did not take.
-    error: a.error ? String(a.error) : null
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
   };
 }
 function toAsset(raw) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipDeclaration, e as ClipLibraryUpdate, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, L as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-DLxz6uFE.js';
-export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipLibraryPlan, p as ClipSource, q as ContextMessage, r as EndCallReason, V as VideoPolicy, s as VideoState, t as isQueued } from './types-DLxz6uFE.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, j as ListSessionsOptions, U as UsageSessionPage, k as UsageSession, l as CreditBalance, T as TranscriptPayload } from './types-BeGuvyra.js';
+export { m as AvatarClip, n as CallConnection, o as CallQueued, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as VideoState, u as isQueued } from './types-BeGuvyra.js';
 
 interface RealtimeAvatarOptions {
     /** `tic_live_…` or `tic_test_…`. Server-side only — never ship this to a browser. */
@@ -74,10 +74,15 @@ declare class RealtimeAvatar {
     /**
      * Register a character from a looping clip you host.
      *
-     * Use a VIDEO source for anything that will be called live. An avatar built from a still
-     * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-     * track dimensions both look fine, only the pixels are wrong. Image sources are for
-     * offline lipsync renders.
+     * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+     * creating from video, in which case it keeps working and your existing avatars are
+     * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+     * resting loop and the motion library from it.
+     *
+     * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+     * or a state switch reads as a jump, and the platform can only guarantee that when it
+     * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+     * it, so the lane could never be made to look right.
      */
     createAvatarFromVideo(input: {
         displayName: string;
@@ -86,17 +91,51 @@ declare class RealtimeAvatar {
         settings?: Record<string, unknown>;
         metadata?: Record<string, unknown>;
     }): Promise<Avatar>;
+    /**
+     * Register a character from ONE still image. The platform generates everything moving:
+     * the resting loop she idles in, then a starter motion library rendered against her rest
+     * pose. No footage, no clip URLs, nothing to shoot.
+     *
+     * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+     * happening — and it is the only chance to direct it, because there is no API today that
+     * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+     * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+     * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+     *
+     * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+     * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+     * a readable error — the motion library is not, and a library failure degrades to
+     * loop-only rather than demoting the character.
+     */
+    createAvatarFromImage(input: {
+        displayName: string;
+        imageUrl: string;
+        motionPrompt?: string;
+        voice?: unknown;
+        settings?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<Avatar>;
     createAvatar(input: {
         displayName: string;
         sourceKind: "image" | "video";
         sourceAssetId: string;
+        /** Art direction for the generated resting loop. Image sources only — a video source
+         *  already IS the loop, and the platform ignores it there. */
+        motionPrompt?: string;
         voice?: unknown;
         settings?: Record<string, unknown>;
         metadata?: Record<string, unknown>;
     }): Promise<Avatar>;
     listAvatars(): Promise<Avatar[]>;
     getAvatar(avatarId: string): Promise<Avatar>;
-    /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+    /**
+     * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+     *
+     * Cheap metadata only. The three things that cost a render have their own methods, because
+     * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+     * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+     * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+     */
     updateAvatar(avatarId: string, patch: AvatarUpdate): Promise<Avatar>;
     /**
      * Re-shoot the character — swap in new footage as her resting loop.
@@ -152,6 +191,64 @@ declare class RealtimeAvatar {
         clips: readonly ClipDeclaration[];
         expectedRevision?: number;
     }): Promise<ClipLibraryUpdate>;
+    /**
+     * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+     * a new one-sentence description.
+     *
+     * Not a clip, and this is the distinction integrations get wrong: a clip with
+     * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+     * she rests in. This is the only thing that does.
+     *
+     * `202`, because the render takes minutes. Three properties, all measured against a real
+     * render rather than asserted:
+     *
+     * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+     *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+     * - **Your clip library is untouched.** Clips render against the portrait, not against the
+     *   loop, so a re-direct re-queues nothing and does not move `revision`.
+     * - **It bills once**, at the rendering model's rate, per re-direct.
+     *
+     * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+     * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+     * re-animate — terminal, do not retry).
+     */
+    setLoop(avatarId: string, loop: {
+        motionPrompt: string;
+    }): Promise<LoopRedirect>;
+    /**
+     * Block until a loop re-direct settles, and throw if it did not take.
+     *
+     * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+     * therefore writes the same polling loop, and the obvious version of it never terminates
+     * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+     * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+     * why this exists rather than a doc line telling you to poll.
+     *
+     * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+     * by the time you can call this the status has already left `ready`.
+     *
+     * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+     * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+     */
+    waitForLoop(avatarId: string, options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Avatar>;
+    /**
+     * Block until every clip in the library has stopped moving.
+     *
+     * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+     * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+     * by pose validation settles `failed`, which is terminal. So this returns the library
+     * with the failures in it and lets you decide; a partial library is a legitimate outcome
+     * and the rest of it is already serving.
+     *
+     * Throws only on timeout.
+     */
+    waitForClips(avatarId: string, options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<ClipLibrary>;
     /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
     listClips(avatarId: string): Promise<ClipLibrary>;
     /**
@@ -216,9 +313,28 @@ declare class RealtimeAvatarError extends Error {
 /**
  * A non-2xx from the API.
  *
- * `code` is the machine-readable reason when the body was JSON — `insufficient_credits` and
- * `spend_limit_exceeded` are the two worth branching on. An HTML body (no `code`) almost
- * always means the route is not served at all rather than that your request was wrong.
+ * `code` is the machine-readable reason when the body was JSON. An HTML body (no `code`)
+ * almost always means the route is not served at all rather than that your request was
+ * wrong.
+ *
+ * The ones worth branching on, and what each one asks you to DO — the distinction that
+ * matters is retry-vs-don't, because a code you cannot classify becomes either a retry loop
+ * against a permanent refusal or a give-up on a transient one:
+ *
+ * | `code` | | |
+ * | --- | --- | --- |
+ * | `insufficient_credits` · `spend_limit_exceeded` | 402 | top up; do not retry |
+ * | `clip_library_not_enabled` | 403 | per-tenant rollout, not a bad request. Nothing about the body will help |
+ * | `loop_not_generatable` | 422 | a grandfathered video-sourced avatar has no portrait to re-animate. **Terminal** |
+ * | `clip_declaration_rejected` · `loop_prompt_rejected` | 422 | the prose was refused; rewrite it |
+ * | `loop_pending` · `anchor_pending` | 409 | one is already in flight — wait, then retry |
+ * | `revision_conflict` | 409 | someone declared first. Re-read `listClips`, re-decide, re-declare |
+ * | `clip_render_limit` | 429 | a true rate limit; nothing was applied. Retry later |
+ * | `clip_screen_unavailable` | 503 | the prose screen could not run. Retry |
+ *
+ * Pose validation does NOT appear here: a rejected upload is not an error response at all.
+ * The declaration is accepted, and that clip settles `status: "failed"` with the verdict in
+ * `poseCheck`.
  *
  * Fields are declared and assigned rather than written as TypeScript parameter properties:
  * that syntax cannot be type-stripped, and this package is meant to run straight from source
@@ -248,4 +364,4 @@ declare function verifyTranscript(rawBody: Uint8Array | string, headers: Headers
     toleranceSeconds?: number;
 }): Promise<TranscriptPayload>;
 
-export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipDeclaration, ClipLibrary, ClipLibraryUpdate, ClipSyncResult, CreditBalance, EndCallOptions, ListSessionsOptions, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, verifyTranscript };
+export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipDeclaration, ClipLibrary, ClipLibraryUpdate, ClipSyncResult, CreditBalance, EndCallOptions, ListSessionsOptions, LoopRedirect, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, verifyTranscript };