Avatar video: avatar_handle or avatar_id per scene?

Use avatar_handle at the top level of POST /v1/avatar-1.0/talking-video. Inside video_inputs a scene can name its avatar with avatar_handle or with a character object that takes avatar_id or avatar_handle. Either way, current execution supports one resolved avatar per final video, and distinct scene avatars are rejected.

Where can I put the avatar reference?

The OpenAPI schema lists three places. A top-level avatar_handle, which is optional when every scene gives its own reference. A per-scene avatar_handle. And a per-scene character object with type: "avatar" plus exactly one of avatar_id or avatar_handle.

The avatar create docs say to use the returned handle or resource id on avatar videos, and the creation response describes avatar_id as read-only, with avatar_handle used in launch generation requests.

What does a valid handle look like?

Handles are Instagram-style: letters, digits, underscores and periods, 2 to 30 characters after an optional leading @. Periods and underscores cannot be first, last or consecutive, and hyphens are not supported. Input is normalized to lowercase without the @.

{
  "video_inputs": [
    {
      "id": "intro",
      "character": {"type": "avatar", "avatar_handle": "@Product_Host"},
      "voice": {"type": "text", "script": "Welcome back."}
    }
  ]
}

What about two presenters?

Render one video per presenter and join the clips afterwards. Giving two different avatars to two scenes in one request is rejected, so plan the cut before you submit.

If the avatar is not ready when you submit, the request returns a 409 with avatar_not_ready; wait for its resource_status to read ready.