---
title: "Update avatar"
method: PATCH
path: "/v1/avatars/{id}"
tags: ["Avatars"]
---

# Update avatar

`PATCH /v1/avatars/{id}`

Update an existing avatar. At least one field must be provided.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Runway-Version` '2024-11-06', required

## Request body

- object
  - `name` string — The character name for the avatar.
  - `referenceImage` union — A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See [our docs](/assets/inputs#images) for supported formats.
    - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
    - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
    - string — A data URI containing encoded media.
  - `personality` string — System prompt defining how the avatar should behave in conversations.
  - `startScript` string, nullable — Optional opening message that the avatar will say when a session starts. Set to null to clear.
  - `voice` union — The voice configuration for the avatar.
    - object — A preset voice from the Runway API.
      - `type` 'runway-live-preset', required
      - `presetId` 'victoria' | 'vincent' | 'clara' | 'drew' | 'skye' | 'max' | 'morgan' | 'felix' | 'mia' | 'marcus' | 'summer' | 'ruby' | 'aurora' | 'jasper' | 'leo' | 'adrian' | 'nina' | 'emma' | 'blake' | 'david' | 'maya' | 'nathan' | 'sam' | 'georgia' | 'petra' | 'adam' | 'zach' | 'violet' | 'roman' | 'luna', required — The ID of a preset voice. Available voices: `victoria` (Victoria), `vincent` (Vincent), `clara` (Clara), `drew` (Drew), `skye` (Skye), `max` (Max), `morgan` (Morgan), `felix` (Felix), `mia` (Mia), `marcus` (Marcus), `summer` (Summer), `ruby` (Ruby), `aurora` (Aurora), `jasper` (Jasper), `leo` (Leo), `adrian` (Adrian), `nina` (Nina), `emma` (Emma), `blake` (Blake), `david` (David), `maya` (Maya), `nathan` (Nathan), `sam` (Sam), `georgia` (Georgia), `petra` (Petra), `adam` (Adam), `zach` (Zach), `violet` (Violet), `roman` (Roman), `luna` (Luna).
    - object — A custom voice created via the Voices API.
      - `type` 'custom', required
      - `id` string, uuid, required — The ID of a custom voice created via the Voices API.
  - `documentIds` string[] — List of knowledge document IDs to attach to this avatar. Replaces all current attachments. Documents provide additional context during conversations.
  - `imageProcessing` 'optimize' | 'none' — Controls image preprocessing. `optimize` improves the image for better avatar results. `none` uses the image as-is; quality not guaranteed.

## Response `200`

Success

- union
  - object — An avatar that is still being processed.
    - `id` string, uuid, required — The unique identifier of the avatar.
    - `name` string, required — The character name for the avatar.
    - `personality` string, required — System prompt defining how the avatar should behave in conversations.
    - `startScript` string, nullable, required — Opening message that the avatar will say when a session starts, or null if not set.
    - `voice` union, required — The voice configured for this avatar.
      - object — A preset voice from the Runway API.
        - `type` 'runway-live-preset', required
        - `presetId` 'victoria' | 'vincent' | 'clara' | 'drew' | 'skye' | 'max' | 'morgan' | 'felix' | 'mia' | 'marcus' | 'summer' | 'ruby' | 'aurora' | 'jasper' | 'leo' | 'adrian' | 'nina' | 'emma' | 'blake' | 'david' | 'maya' | 'nathan' | 'sam' | 'georgia' | 'petra' | 'adam' | 'zach' | 'violet' | 'roman' | 'luna', required — The preset voice identifier.
        - `name` string, required — The display name of the voice.
        - `description` string, required — A brief description of the voice characteristics.
      - object — A custom voice created via the Voices API.
        - `type` 'custom', required
        - `id` string, uuid, required — The unique identifier of the custom voice.
        - `deleted` boolean, required — Whether the voice has been deleted. When true, name and description are omitted.
        - `name` string — The display name of the voice.
        - `description` string, nullable — A brief description of the voice characteristics.
    - `referenceImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the avatar's reference image.
    - `processedImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the processed reference image.
    - `documentIds` string[], required — IDs of knowledge documents attached to this avatar.
    - `createdAt` string, date-time, required — When the avatar was created.
    - `updatedAt` string, date-time, required — When the avatar was last updated.
    - `status` 'PROCESSING', required
  - object — An avatar that is ready for use in sessions.
    - `id` string, uuid, required — The unique identifier of the avatar.
    - `name` string, required — The character name for the avatar.
    - `personality` string, required — System prompt defining how the avatar should behave in conversations.
    - `startScript` string, nullable, required — Opening message that the avatar will say when a session starts, or null if not set.
    - `voice` union, required — The voice configured for this avatar.
      - object — A preset voice from the Runway API.
        - `type` 'runway-live-preset', required
        - `presetId` 'victoria' | 'vincent' | 'clara' | 'drew' | 'skye' | 'max' | 'morgan' | 'felix' | 'mia' | 'marcus' | 'summer' | 'ruby' | 'aurora' | 'jasper' | 'leo' | 'adrian' | 'nina' | 'emma' | 'blake' | 'david' | 'maya' | 'nathan' | 'sam' | 'georgia' | 'petra' | 'adam' | 'zach' | 'violet' | 'roman' | 'luna', required — The preset voice identifier.
        - `name` string, required — The display name of the voice.
        - `description` string, required — A brief description of the voice characteristics.
      - object — A custom voice created via the Voices API.
        - `type` 'custom', required
        - `id` string, uuid, required — The unique identifier of the custom voice.
        - `deleted` boolean, required — Whether the voice has been deleted. When true, name and description are omitted.
        - `name` string — The display name of the voice.
        - `description` string, nullable — A brief description of the voice characteristics.
    - `referenceImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the avatar's reference image.
    - `processedImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the processed reference image.
    - `documentIds` string[], required — IDs of knowledge documents attached to this avatar.
    - `createdAt` string, date-time, required — When the avatar was created.
    - `updatedAt` string, date-time, required — When the avatar was last updated.
    - `status` 'READY', required
  - object — An avatar that failed to finish processing.
    - `id` string, uuid, required — The unique identifier of the avatar.
    - `name` string, required — The character name for the avatar.
    - `personality` string, required — System prompt defining how the avatar should behave in conversations.
    - `startScript` string, nullable, required — Opening message that the avatar will say when a session starts, or null if not set.
    - `voice` union, required — The voice configured for this avatar.
      - object — A preset voice from the Runway API.
        - `type` 'runway-live-preset', required
        - `presetId` 'victoria' | 'vincent' | 'clara' | 'drew' | 'skye' | 'max' | 'morgan' | 'felix' | 'mia' | 'marcus' | 'summer' | 'ruby' | 'aurora' | 'jasper' | 'leo' | 'adrian' | 'nina' | 'emma' | 'blake' | 'david' | 'maya' | 'nathan' | 'sam' | 'georgia' | 'petra' | 'adam' | 'zach' | 'violet' | 'roman' | 'luna', required — The preset voice identifier.
        - `name` string, required — The display name of the voice.
        - `description` string, required — A brief description of the voice characteristics.
      - object — A custom voice created via the Voices API.
        - `type` 'custom', required
        - `id` string, uuid, required — The unique identifier of the custom voice.
        - `deleted` boolean, required — Whether the voice has been deleted. When true, name and description are omitted.
        - `name` string — The display name of the voice.
        - `description` string, nullable — A brief description of the voice characteristics.
    - `referenceImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the avatar's reference image.
    - `processedImageUri` string, nullable, required — A URI pointing to a low-resolution preview of the processed reference image.
    - `documentIds` string[], required — IDs of knowledge documents attached to this avatar.
    - `createdAt` string, date-time, required — When the avatar was created.
    - `updatedAt` string, date-time, required — When the avatar was last updated.
    - `status` 'FAILED', required
    - `failureReason` string, required — A human-readable error message. This value is not stable and should not be matched against programmatically.

## Other responses

- `409` — The reference image cannot be updated while the avatar is processing.

---

[API](https://skmtc.net/runwayml/apis/runwayml-api.md) · [All operations](https://skmtc.net/runwayml/apis/runwayml-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runwayml/runwayml-api/versions/e7d9a59ac7b0/schema)