Cara-4 as go-to model for python examples

README.md

@@ -170,7 +170,7 @@ client = AnamClient(
         llm_id="your-llm-id",
         name="My Assistant",
         system_prompt="You are a helpful assistant...",
-        avatar_model="cara-3",
+        avatar_model="cara-4",
         language_code="en",
         enable_audio_passthrough=False,
     ),
@@ -488,12 +488,16 @@ persona = PersonaConfig(
     avatar_id="your-avatar-id",       # From https://lab.anam.ai/avatars (do not use persona_id)
     voice_id="your-voice-id",         # From https://lab.anam.ai/voices
     llm_id="your-llm-id",             # From https://lab.anam.ai/llms (optional)
-    avatar_model="cara-3",            # Video frame model (optional)
+    avatar_model="cara-4",            # Video frame model (optional)
     system_prompt="You are...",       # See https://docs.anam.ai/concepts/prompting-guide
     enable_audio_passthrough=False,
 )
 ```
 
+### Avatar model
+
+Set `avatar_model` on ephemeral `PersonaConfig`. If your avatar does not support Cara-4, use `avatar_model="cara-3"` or if you require Cara-4, generate a new avatar in [lab.anam.ai](https://lab.anam.ai). New avatars will support the "cara-4" model.
+
 ### Orchestration
 
 Orchestration is the process of running a pipeline with different components to transform user audio into a response (STT -> LLM -> TTS -> Avatar). 

examples/avatar_audio_passthrough.py

@@ -199,6 +199,7 @@ def main() -> None:
 
     persona_config = PersonaConfig(
         avatar_id=avatar_id,
+        avatar_model=os.environ.get("ANAM_AVATAR_MODEL", "cara-4").strip().strip('"') or None,
         enable_audio_passthrough=True,
     )
 

examples/persona_interactive_video.py

@@ -18,7 +18,7 @@
     export ANAM_AVATAR_ID="your-avatar-id"
     export ANAM_VOICE_ID="your-voice-id"
     export ANAM_LLM_ID="your-llm-id"
-    export ANAM_AVATAR_MODEL="model-name"     # optional, e.g. "cara-3"
+    export ANAM_AVATAR_MODEL="model-name"     # optional, e.g. "cara-4"
     uv run --extra display python examples/persona_interactive_video.py
 """
 
@@ -286,7 +286,7 @@ def main() -> None:
     api_key = os.environ.get("ANAM_API_KEY", "").strip().strip('"')
     avatar_id = os.environ.get("ANAM_AVATAR_ID", "").strip().strip('"')
     voice_id = os.environ.get("ANAM_VOICE_ID", "").strip().strip('"')
-    avatar_model = os.environ.get("ANAM_AVATAR_MODEL")
+    avatar_model = os.environ.get("ANAM_AVATAR_MODEL", "cara-4").strip().strip('"') or None
     llm_id = os.environ.get("ANAM_LLM_ID", "").strip().strip('"')
     api_base_url = os.environ.get("ANAM_API_BASE_URL", "https://api.anam.ai").strip().strip('"')
 
@@ -310,7 +310,7 @@ def main() -> None:
     #   - avatar_id: the "face" (https://lab.anam.ai/avatars). Do not use persona_id as avatar_id.
     #   - voice_id: voice for TTS (https://lab.anam.ai/voices).
     #   - llm_id: LLM for reasoning (https://lab.anam.ai/llms).
-    #   - avatar_model: video frame model (e.g. "cara-3").
+    #   - avatar_model: video frame model (e.g. "cara-4").
     #   - system_prompt: primes the LLM. See https://docs.anam.ai/concepts/prompting-guide
     #
     # enable_audio_passthrough:

examples/text_to_video.py

@@ -19,7 +19,7 @@
     export ANAM_API_KEY="your-api-key"
     export ANAM_AVATAR_ID="your-avatar-id"
     export ANAM_VOICE_ID="your-voice-id"
-    export ANAM_AVATAR_MODEL="cara-3"    # optional, defaults to cara-3
+    export ANAM_AVATAR_MODEL="cara-4"    # optional, defaults to cara-4
     export ANAM_LLM_ID="your-llm-id"     # optional, uses default Anam LLM
     uv run python examples/text_to_video.py "Hello, how are you today?"
 """
@@ -205,7 +205,7 @@ async def text_to_video(
         persona_id: Persona ID to use.
         avatar_id: Avatar ID for ephemeral persona.
         voice_id: Voice ID for ephemeral persona.
-        avatar_model: Avatar model version (e.g., 'cara-3').
+        avatar_model: Avatar model version (e.g., 'cara-4').
 
     Returns:
         Path to the output video file.
@@ -231,7 +231,7 @@ async def text_to_video(
     if not voice_id:
         voice_id = os.environ.get("ANAM_VOICE_ID", "").strip().strip('"')
     if not avatar_model:
-        avatar_model = os.environ.get("ANAM_AVATAR_MODEL", "cara-3").strip().strip('"')
+        avatar_model = os.environ.get("ANAM_AVATAR_MODEL", "cara-4").strip().strip('"') or None
 
     # Determine mode - prefer avatar_id + voice_id if both provided
     if avatar_id and voice_id:

examples/user_audio_from_wav.py

@@ -13,7 +13,7 @@
     export ANAM_AVATAR_ID="your-avatar-id"
     export ANAM_VOICE_ID="your-voice-id"
     export ANAM_LLM_ID="your-llm-id"  # optional
-    export ANAM_AVATAR_MODEL="cara-3"  # optional
+    export ANAM_AVATAR_MODEL="cara-4"  # optional
     uv run python examples/user_audio_from_wav.py path/to/input.wav
 """
 
@@ -67,7 +67,7 @@ def _build_persona_config() -> PersonaConfig:
     avatar_id = os.environ.get("ANAM_AVATAR_ID", "").strip().strip('"')
     voice_id = os.environ.get("ANAM_VOICE_ID", "").strip().strip('"')
     llm_id = os.environ.get("ANAM_LLM_ID", "").strip().strip('"')
-    avatar_model = os.environ.get("ANAM_AVATAR_MODEL", "").strip().strip('"') or None
+    avatar_model = os.environ.get("ANAM_AVATAR_MODEL", "cara-4").strip().strip('"') or None
 
     return PersonaConfig(
         avatar_id=avatar_id,

src/anam/types.py

@@ -55,7 +55,7 @@ class PersonaConfig:
         persona_id: The ID of the persona to use - Only uses pre-defined personas. All other parameters are ignored, except enable_audio_passthrough.
         name: Display name for the persona (optional).
         avatar_id: The avatar to use for video (from: https://lab.anam.ai/avatars). Do not use persona_id as avatar_id.
-        avatar_model: Avatar model version (e.g., 'cara-3') (optional).
+        avatar_model: Avatar model version (e.g., 'cara-4') (optional).
         voice_id: The voice to use for audio (optional, uses persona default).
         system_prompt: Custom system prompt for the persona (optional).
         language_code: Language code (e.g., 'en', 'es') (optional).