GymVoice API — The first API that knows the gym floor

How it works

From query to voice
in one request

No prompt engineering, no audio pipeline to manage. Pass a gym ID and a natural language query — the API handles everything else.

Step 01

📡

Send a query + gym ID

POST your user's query and the gym's unique ID to the /v1/voice endpoint with your Bearer token.

Step 02

🗺️

API loads the gym floor plan

The API fetches the gym's complete floor plan from the xAI collection — every machine, zone, and coordinate. No two gyms return the same response.

Step 03

🧠

Grok builds a personalised response

Grok receives the query combined with full gym context — equipment availability, zone layout, and machine positions — and generates a precise, floor-aware answer.

Step 04

🔊

ElevenLabs returns natural voice audio

The text is rendered to natural speech via ElevenLabs. You receive an MP3 URL and the transcript — ready to play directly in your app or interface.

Pricing

Simple, usage-based pricing

No sales calls required for Starter and Pro. Sign up, get a key, start building. Scale when you need to.

Starter

^£99

per month

Up to 5,000 interactions / month

Full gym floor plan awareness
xAI / Grok-powered responses
ElevenLabs voice synthesis
MP3 audio URL + text transcript
Standard support
£0.075 per interaction over limit

Get started

One endpoint.
Everything you need.

Endpoints

POST /v1/voice STABLE

Reference

Authentication Error codes

Authentication

All requests require a Bearer token in the Authorization header. Your API key is issued when you sign up.

# All API requests
Authorization: Bearer YOUR_API_KEY

POST https://api.gymfloor.ai/v1/voice

Generate a gym-aware spoken response. The API loads the specified gym's floor plan from the xAI collection, passes it as context to Grok, and renders the response to audio via ElevenLabs. Returns an MP3 URL and transcript within a single response object.

Request body

Parameter	Type		Description
gymId	string	required	The unique identifier for the gym. Used to fetch the floor plan from the xAI gym collection.
query	string	required	The natural language query to answer — e.g. "Where is the cable machine?" or "What should I do for chest today?"
userId	string	optional	Your end-user's identifier. Used for personalisation and usage attribution. Not stored by GymVoice.
voiceId	string	optional	ElevenLabs voice ID to use for synthesis. Defaults to a clear, neutral coach voice if omitted.

Response

Field	Type	Description
audioUrl	string	Signed URL to the generated MP3 audio file. Valid for 1 hour.
text	string	The full text transcript of the spoken response.
latencyMs	number	Total end-to-end processing time in milliseconds, from receipt to audio URL ready.

Examples

cURL

JavaScript

curl https://api.gymfloor.ai/v1/voice \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gymId": "gym_abc123",
    "query": "Where is the cable machine and how do I set it up for lat pulldowns?",
    "userId": "user_xyz",
    "voiceId": "EXAVITQu4vr4xnSDxMaL"
  }'
const response = await fetch('https://api.gymfloor.ai/v1/voice', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gymId: 'gym_abc123',
    query: 'Where is the cable machine and how do I set it up for lat pulldowns?',
    userId: 'user_xyz',
    voiceId: 'EXAVITQu4vr4xnSDxMaL',
  }),
});

const data = await response.json();

// data.audioUrl  — play this MP3 directly
// data.text      — full transcript
// data.latencyMs — e.g. 743

const audio = new Audio(data.audioUrl);
audio.play();

Response example

{ "audioUrl": "https://storage.gymfloor.ai/voice/clip_9kXp2q.mp3", "text": "The cable machine is in Zone B, near the free weights area. To set up for lat pulldowns, attach the wide-grip bar, set the weight stack to your target load, then kneel or sit and pull the bar down to your upper chest.", "latencyMs": 743 }

Error codes

Code	Meaning
401	Invalid or missing API key.
404	`gymId` not found in the xAI gym collection.
429	Rate limit exceeded. Check your plan's interaction limit.
500	Upstream error from Grok or ElevenLabs. Retryable.

The first API that knows the gym floor.

From query to voicein one request