#
AI Services API
Standalone AI generation, food image scanning with Google Vertex AI, and voice AI coaching with Hume's Empathic Voice Interface. All endpoints require X-API-Key.
#
Standalone AI Generation
These endpoints generate plans without saving them to a user account. They are useful for previewing plans or building custom workflows. For plans that are saved and tracked, see User Management & Plans.
#
Generate Workout Plan
POST /ai/generate-workout-plan
{
"userProfile": {
"age": 28,
"gender": "female",
"weight": 65,
"height": 170,
"fitnessLevel": "intermediate",
"goals": ["weight_loss", "strength"],
"workoutDays": ["mon", "wed", "fri", "sat"],
"sessionDuration": 45,
"equipment": ["dumbbells", "resistance_bands"],
"injuries": ["lower_back"]
},
"preferences": {
"daysPerWeek": 4,
"intensity": "medium",
"duration": "6 weeks"
}
}{
"success": true,
"data": {
"workoutPlan": {
"title": "Intermediate Strength & Weight Loss Program",
"description": "6-week progressive program",
"duration": "6 weeks",
"daysPerWeek": 4,
"weeks": [
{
"week": 1,
"days": [
{
"day": 1,
"name": "Upper Body Strength",
"exercises": [
{
"name": "Dumbbell Bench Press",
"sets": 3,
"reps": "10-12",
"restTime": "60-90 seconds",
"instructions": "..."
}
]
}
]
}
]
}
}
}
#
Generate Nutrition Plan
POST /ai/generate-nutrition-plan
{
"userProfile": {
"age": 28,
"gender": "female",
"weight": 65,
"height": 170,
"goals": ["weight_loss"],
"dietaryRestrictions": ["vegetarian"]
},
"preferences": {
"mealTypes": ["breakfast", "lunch", "dinner"],
"duration": "7 days",
"targetCalories": 1800
}
}
#
Generate Class Plan
POST /ai/generate-class-plan
{
"userProfile": {
"age": 32,
"fitnessLevel": "intermediate",
"goals": ["strength", "flexibility"],
"availableDays": ["mon", "wed", "fri"]
},
"preferences": {
"daysPerWeek": 3,
"duration": "4 weeks",
"sessionDuration": 60
}
}
#
Food Scanning
AI-powered food image analysis using Google Vertex AI Gemini models. Identifies foods, estimates portions, and provides detailed nutritional breakdowns.
#
Scan Food
POST /food-scanner/scan-food
Analyse a food image. Supports two upload methods:
curl -X POST https://api.studiostv.net/api/v1/food-scanner/scan-food \
-H "X-API-Key: your-api-key" \
-F "image=@meal-photo.jpg"curl -X POST https://api.studiostv.net/api/v1/food-scanner/scan-food \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{ "image": "data:image/jpeg;base64,/9j/4AAQ..." }'const formData = new FormData();
formData.append('image', imageFile);
const response = await fetch(`${BASE_URL}/food-scanner/scan-food`, {
method: 'POST',
headers: { 'X-API-Key': apiKey },
body: formData
});
const { data } = await response.json();
const { identifiedFood, nutritionFactsPerPortion } = data.foodAnalysis;import requests
with open('meal-photo.jpg', 'rb') as image_file:
response = requests.post(
f'{BASE_URL}/food-scanner/scan-food',
headers={'X-API-Key': api_key},
files={'image': image_file}
)
analysis = response.json()['data']['foodAnalysis']
print(f"Food: {analysis['identifiedFood']}")
print(f"Calories: {analysis['nutritionFactsPerPortion']['calories']}")Supported formats: JPEG, PNG, WebP (max 10MB)
Response:
{
"success": true,
"data": {
"foodAnalysis": {
"identifiedFood": "Grilled chicken breast with mixed vegetables",
"portionSize": "200 grams",
"recognizedServingSize": "200 grams",
"nutritionFactsPerPortion": {
"calories": "285",
"protein": "35g",
"carbs": "12g",
"fat": "8g",
"fiber": "4g",
"sugar": "6g",
"sodium": "320mg",
"cholesterol": "85mg"
},
"nutritionFactsPer100g": {
"calories": "142",
"protein": "17.5g",
"carbs": "6g",
"fat": "4g",
"fiber": "2g",
"sugar": "3g",
"sodium": "160mg",
"cholesterol": "42mg"
},
"additionalNotes": [
"High protein content ideal for muscle building",
"Low in saturated fat",
"Gluten-free and dairy-free"
]
}
}
}
#
Supported Formats
GET /food-scanner/supported-formats
Get the list of supported image formats and size limits.
#
Voice AI (Hume EVI)
sTvOS integrates with Hume's Empathic Voice Interface for conversational AI coaching. The voice agent runs in LiveKit rooms and can execute tool calls against the user's data.
#
Hume Configuration
Per-trainer personalities
Each trainer can have a separate Hume chat configuration, allowing different voice AI personalities. Set humeChatConfigId per trainer to customise the coaching experience.
#
Voice AI Tools
Endpoints the Hume EVI agent calls during conversations. These require X-API-Key + Bearer token.
#
Hume Webhook
The webhook endpoint Hume AI calls for events. Authenticated via HMAC signature validation (not API key).
#
LiveKit Token
POST /livekit/token
Generate a LiveKit access token for joining a voice or video room. Bearer token is optional -- omit it for anonymous sessions (onboarding).
{
"roomName": "coaching-session-123",
"context": "User wants to discuss their workout plan",
"agentName": "fitness-coach"
}{
"success": true,
"data": {
"token": "eyJhbGciOi...",
"wsUrl": "wss://livekit.example.com",
"roomName": "coaching-session-123"
}
}Anonymous vs authenticated
When a bearer token is provided, the user ID is embedded in the LiveKit token identity. Without a bearer token, a generated identity is used. This allows voice sessions during onboarding before the user has an account.
#
FAQ
How long does food scanning take?
Typically 3-8 seconds depending on image complexity. The response includes full nutritional data and identified food items.
Can I use food scanning results for nutrition logging?
Yes. After scanning, pass the nutritional data to POST /progress/nutrition to log the meal. This creates a scan-to-log workflow.
How does the voice AI know about the user?
When a bearer token is provided with the LiveKit token request, the Hume agent has access to the user's profile, plans, bookings, and progress through tool calls. The context field in the token request provides additional situational context.