The official Python client for the WorkoutX API. Query API v2's 1,900+ exercises (2,700+ clips as 720p MP4 animations, male and female models, instructions, tips and anatomical muscle names), generate workouts, fetch supplements, and run Body Scans. Perfect for backend services, data science notebooks, and AI coaching tools. Minimal dependencies, type-hinted, works everywhere Python runs.
✓ Live on PyPI — pypi.org/project/workoutx-sdk · supports Python 3.8+.
Create one client with your API key and use wx.v2. The SDK sends the key in the X-WorkoutX-Key header, the only place v2 accepts it. The same client also covers the v1 resources and the Body Scan API (user JWT).
Clean dictionaries you can drop straight into pandas, ML pipelines, or an LLM-powered coaching agent. v2's instructions, tips and anatomical muscle names make good context.
fresh_media(id) reuses the signed links from earlier calls until about 5 minutes before they expire, then fetches new ones. You store exercise ids; the SDK keeps the links valid.
Automatic retries with backoff on 429 and 5xx, honoring Retry-After. A used-up quota is not retried. Structured WorkoutXError with status, code and tips.
Python runs on your server, so it doesn't play video itself: return the media links to your web or mobile client and let it play mp4 directly. Links are signed, expire after about 24 hours and contain no API key, so they're safe to hand out. Store exercise ids, never media URLs, and call fresh_media(id) when a client needs links.
On the client, play mp4 muted and looping and show poster while it loads. The MP4 is a 600×720 loop at 30 fps (usually 100–300 KB); on the Free plan both links are 300×360 watermarked previews.
Don't download, proxy or re-host the files: serving them from your own servers or CDN isn't permitted on any plan. See Media in v2 for players on iOS, Android and Flutter.
Male and female versions are separate exercises. counterpartId points at the same movement with the other model, so you can offer a switch, and model filters a list to one of them. lang returns names, instructions, tips and muscles in Turkish (tr), German (de), Spanish (es), French (fr), Simplified Chinese (zh-SG) or Traditional Chinese (zh-HK). English is the default; filter values stay in English.
Similar exercises, alternatives with other equipment and calorie estimates, on v2 ids. Ranked results are full v2 exercises with media links plus a score, and never include the exercise itself or its other-model clip. All three take lang. Parameters keep the API's camelCase names (weightKg, excludeEquipment), as in the v1 resources.
v2.workout.generate() returns one session from the rule-based workout engine: a warm-up, exercises grouped into blocks (straight sets, supersets such as C1/C2, or one circuit) with sets, reps or a duration, rest, effort (rir) and swap alternatives, then a cool-down. Every exercise in it, warm-up and cool-down items included, is a full v2 exercise with media links, and model picks the male or female clips. avoidJoints (knee, shoulder, lumbar_spine, elbow, wrist, hip, ankle) leaves out movements that load those joints heavily; it is general guidance, not medical advice. format picks straight, superset or circuit (default auto). The response carries estimatedDurationMinutes and the seed it used; pass the seed back to get the same workout. v2.workout.program() returns a schedule, the week-by-week program and an exerciseLibrary that its exercises reference by exerciseId. The generator needs Growth or Scale (legacy Pro, Ultra); multi-week programs need Scale (legacy Ultra).
The evidence-graded supplement database in the v2 page shape, {"total", "limit", "offset", "results", "disclaimer"}. Growth and Scale (legacy Pro, Ultra); stacks need Scale (legacy Ultra). Informational content only, not medical advice. Supplement text is English.
Narrow v2.list() by the joint a movement works through, an intensity band and descriptive tags, for physical therapy, mobility and senior-fitness apps. Growth and Scale (legacy Ultra). These are descriptive fields, not medical recommendations.
v1 keeps working on the same key, and you'll get at least 30 days' notice before it's retired. The SDK's v1 resources (exercises, gifs, workout, supplements) are unchanged, so you can move one screen at a time. Map each v1 id you've stored once with v2.legacy() and save the v2 id: 1,324 of the 1,327 v1 exercises have a v2 match.
Step by step, with code for each platform: the v2 migration guide.
Every non-2xx response raises a WorkoutXError with status, code, tip and the parsed body. A feature your plan doesn't include answers 403 and names the plan that has it. A 429 is either a rate limit, which the SDK retries with backoff, or a used-up request quota, which it doesn't retry. The Free plan's 500 requests are a one-time allowance.
Run pip install workoutx-sdk. It supports Python 3.8+ and has minimal dependencies (only certifi for reliable TLS). API v2 lives under wx.v2.
Return wx.v2.fresh_media(id) from your backend and play mp4 on the client in a muted, looping video player, with poster as the still frame. Don't download, proxy or re-host the files.
No. Media links are signed and expire after about 24 hours. Store exercise ids and call fresh_media(id) when you need links; it reuses them until they're close to expiry.
Yes. Responses are plain Python dicts/lists, so they slot directly into pandas, scikit-learn pipelines, or prompts for an LLM agent. v2 adds instructions, form tips and anatomical muscle names.
Yes. wx.exercises, wx.gifs, wx.workout and wx.supplements still call v1, which keeps working; you'll get at least 30 days' notice before it's retired. wx.v2.legacy(v1_id) maps the v1 ids you've stored to v2.
Create a free account in the Developer Portal and copy your wx_... key. Pass it as api_key. The Free plan includes 500 requests in total with watermarked previews; paid plans start at $19 a month.
Body Scan uses a logged-in user's JWT. Pass scan_token=, or scan_email= and scan_password= to let the SDK log in automatically.
Load your API key from an environment variable or secret manager rather than hard-coding it. Never commit keys to version control. v2 accepts the key only in the X-WorkoutX-Key header, which the SDK sets for you.
fresh_media() returns signed links that expire after about 24 hours and contain no API key, so your API can pass them to web and mobile clients. Store exercise ids, not links. (v1's gif_url() still puts the key in the URL.)
The Body Scan scan_email/scan_password auto-login should only run in trusted server environments — not in code shipped to end users.
Start free with 500 requests and watermarked previews. 1,900+ exercises as 720p video, workouts, and Body Scan in one SDK.
Get your free API key