---
title: "Generate avatar video from audio or text"
method: POST
path: "/v1/avatar_videos"
tags: ["Avatar Videos"]
---

# Generate avatar video from audio or text

`POST /v1/avatar_videos`

Start an asynchronous task to generate a video of an avatar speaking. Provide `speech` with `type: "audio"` (audio file) or `type: "text"` (text script for TTS). Poll `GET /v1/tasks/:id` to check progress and retrieve the output video URL once complete.

## Headers

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

## Request body

- object
  - `model` 'gwm1_avatars', required — The model to use for avatar video generation.
  - `avatar` union, required — The avatar configuration for the session.
    - object — A preset avatar from Runway.
      - `type` 'runway-preset', required
      - `presetId` 'game-character' | 'music-superstar' | 'game-character-man' | 'cat-character' | 'influencer' | 'tennis-coach' | 'human-resource' | 'fashion-designer' | 'cooking-teacher', required — ID of a preset avatar.
    - object — A user-created avatar.
      - `type` 'custom', required
      - `avatarId` string, uuid, required — ID of a user-created avatar.
  - `speech` union, required — The speech source for avatar video generation. Either an audio file or text script.
    - object — Provide an audio file for the avatar to speak.
      - `type` 'audio', required
      - `audio` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio 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.
    - object — Provide text for the avatar to speak via TTS.
      - `type` 'text', required
      - `text` string, required — Text script for speech-driven video generation.
      - `voice` union — Optional voice override for TTS. If not provided, the avatar's configured voice is used.
        - object — A preset voice from the Runway API.
          - `type` '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
        - object — A custom voice created via the Voices API.
          - `type` 'custom', required
          - `id` string, uuid, required

## Response `200`

Success

- object
  - `id` string, uuid, required — The ID of the avatar video task. Use `GET /v1/tasks/:id` to poll for status and output.

## Changes

- **2026-06-02** `bb2963960c9b` — 1 info
  - the `speech/oneOf[subschema #2: TextInput]/text` request property's maxLength was increased from `3000` to `5000`
- **2026-04-30** `1d3bb312672a` — 1 info
  - the `speech/oneOf[subschema #2: TextInput]/text` request property's maxLength was increased from `1000` to `3000`
- **2026-04-15** `6f5bc53a0d36` — 1 warning
  - changed the pattern of the request property `speech/oneOf[subschema #1: AudioInput]/audio/anyOf[subschema #1]/` from `^https://.*` to `^https:\/\/.*`
- **2026-04-10** `ee023fb84f0e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/runwayml/apis/runwayml-api/changes/v1/avatar_videos/post.md)

---

[API](https://skmtc.dev/runwayml/apis/runwayml-api.md) · [All operations](https://skmtc.dev/runwayml/apis/runwayml-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runwayml/runwayml-api/revisions/efc9e5abc4d0/schema)