Introduction

export AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

$env:AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

const response = await fetch('https://api.agenthuman.com/v1/sessions', {
  headers: { 'x-api-key': API_KEY }
});

const remaining = response.headers.get('RateLimit-Remaining');
if (parseInt(remaining) < 10) {
  console.warn('Approaching rate limit, consider slowing down');
}

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    // Exponential backoff: 1s, 2s, 4s, etc.
    const delay = Math.pow(2, i) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Max retries exceeded');
}

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedAvatars() {
  const cached = cache.get('avatars');
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const response = await fetch('https://api.agenthuman.com/v1/avatars', {
    headers: { 'x-api-key': API_KEY }
  });
  const data = await response.json();
  
  cache.set('avatars', { data, timestamp: Date.now() });
  return data;
}

npm install axios dotenv

pip install requests python-dotenv

const headers = { 'x-api-key': API_KEY };

// 1) List characters
const charactersRes = await fetch('https://api.agenthuman.com/v1/avatars', { headers });
const { avatars: characters } = await charactersRes.json();
const character = characters[0];

// 2) List looks (session-ready avatars) for that character
const looksRes = await fetch(
  `https://api.agenthuman.com/v1/avatars?parent_id=${encodeURIComponent(character.avatar_id)}`,
  { headers }
);
const { avatars: looks } = await looksRes.json();
const look = looks[0];

// 2. Create a session
const createRes = await fetch('https://api.agenthuman.com/v1/sessions', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    avatar_id: look.avatar_id,
    metadata: { user_id: 'user_123' }
  })
});
const { session } = await createRes.json();

// 3. Start the session to activate the avatar server
const startRes = await fetch(
  `https://api.agenthuman.com/v1/sessions/${session.session_id}/start`,
  {
    method: 'POST',
    headers: { 'x-api-key': API_KEY }
  }
);
const { ws_uri } = await startRes.json();

// 4. Connect to Daily.co room for WebRTC video
// Use session.daily_room.url and session.daily_room.token

// 5. End the session when done
const endRes = await fetch(
  `https://api.agenthuman.com/v1/sessions/${session.session_id}/end`,
  {
    method: 'POST',
    headers: { 'x-api-key': API_KEY }
  }
);
const { session: endedSession } = await endRes.json();
console.log(`Session duration: ${endedSession.duration} seconds`);

import requests

API_KEY = os.getenv('AGENTHUMAN_API_KEY')
headers = {'x-api-key': API_KEY}

# Get all active sessions
active_res = requests.get(
  'https://api.agenthuman.com/v1/sessions?status=started',
  headers=headers
)
active_sessions = active_res.json()['sessions']
print(f"Active sessions: {len(active_sessions)}")

# Get sessions for a specific avatar
avatar_res = requests.get(
  f'https://api.agenthuman.com/v1/sessions?avatar_id={avatar_id}',
  headers=headers
)
avatar_sessions = avatar_res.json()['sessions']

# Get detailed info for a specific session
session_res = requests.get(
  f'https://api.agenthuman.com/v1/sessions/{session_id}',
  headers=headers
)
session_details = session_res.json()['session']
print(f"Session with {session_details['avatar']['name']}")

async function createSessionSafely(avatarId) {
  try {
    const response = await fetch('https://api.agenthuman.com/v1/sessions', {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ avatar_id: avatarId })
    });
    
    const data = await response.json();
    
    // Most /v1 endpoints return { success: boolean, ... }, but auth/middleware
    // failures may return { error: string }.
    if (!response.ok || data.success === false) {
      const errorMessage =
        typeof data.error === 'string'
          ? data.error
          : data.error?.message || data.error || 'Request failed';

      console.error('API Error:', errorMessage);

      const suggestion = typeof data.error === 'object' ? data.error?.suggestion : undefined;
      if (suggestion) console.log('Suggestion:', suggestion);

      return null;
    }
    
    return data.session;
  } catch (error) {
    // Handle network error
    console.error('Network error:', error.message);
    return null;
  }
}