---
title: "Re-direct an avatar's resting loop"
method: PUT
path: "/v1/avatars/{avatarId}/loop"
tags: ["Avatars"]
---

# Re-direct an avatar's resting loop

`PUT /v1/avatars/{avatarId}/loop`

## Request

- Base URL: `https://realtimeavatar.ai/api`
- URL: `https://realtimeavatar.ai/api/v1/avatars/{avatarId}/loop`
- Auth: HTTP bearer

Re-direct the avatar's RESTING LOOP — the video she plays when nothing else is happening — from a new one-sentence description. Not a clip: a clip with role "idle" is a variant spliced OVER the loop, and declaring one never changes what she rests in. 202; the render takes minutes, during which she stays ready and keeps serving her previous loop (returned as servingUrl), and the swap publishes atomically once the new loop is usable. The clip library is untouched. Billed as one generation at the rendering model's rate. Needs a portrait to re-animate: 422 loop_not_generatable (terminal) on a grandfathered avatar built from a supplied video with no portrait — the gate is the portrait, not sourceKind, which reads "video" on every avatar once its generated loop has attached. Supports Idempotency-Key replay — send one on retries, because a repeated re-direct is a second billed render.

Requires an API key with the `avatars:write` scope.

## Path parameters

- `avatarId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- PutAvatarLoopRequest
  - `motionPrompt` string, required

## Response `202`

Re-direct accepted

- PutAvatarLoopResponse
  - `avatarId` string, required
  - `loopStatus` 'generating' | 'ready' | 'failed', required
  - `motionPrompt` string, required
  - `servingUrl` string, uri, nullable, required

## Other responses

- `401`: Missing, malformed, revoked, or expired key.
- `403`: The key lacks the scope for this operation, or the tenant is not active.
- `default`: Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads "does not belong to this tenant", which is a missing id and not a permission failure), 408 (the request was cancelled), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 504 (the upstream request budget expired), 500 (unhandled). Switch on `code` where present, else `status`.

---

[API](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api.md) · [All operations](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api/revisions/e9e3e998e673?raw)