Workouts

Generate a structured workout

get/workouts/generate

Request

Base URL: https://exercise-api.ymove.app/api/v2
URL: https://exercise-api.ymove.app/api/v2/workouts/generate
Auth: one of:
- API key in header X-API-Key
- API key in query parameter api_key

Query parameters

muscleGroupstring[] required

Target muscle group(s). Accepts a single value, a comma-separated list (e.g. "chest,back"), or repeated query keys. Aliases: "full_body" (all groups), "upper_body" (chest, back, shoulders, biceps, triceps, forearms, core), "lower_body" (quads, hamstrings, glutes, calves, legs). Aliases can be combined with specific groups. Synonyms and finer-grained muscles also roll up to their group.

equipmentstring[]

Limit to specific equipment. Accepts a single value, comma-separated list, or repeated keys. Hyphens, underscores and spaces are interchangeable.

exerciseTypestring[]

Filter main exercises by type. Accepts a single value, comma-separated list, or repeated keys.

difficulty'beginner' | 'intermediate' | 'advanced'

Difficulty level. Filters which exercises are selected: beginner returns beginner-level moves, intermediate returns beginner+intermediate, advanced prefers advanced moves (falling back to intermediate where advanced options are limited). Also sets the default set/rep/rest scheme.

exerciseCountinteger

Number of main exercises (warmup and cooldown are returned separately and counted in addition to this).

structure'straight' | 'superset' | 'circuit' | 'auto'

Workout structure. auto lets the generator pick: straight for advanced (heavy work needs full rest) or single-muscle requests, circuit for bodyweight-only sessions of 5+ exercises, supersets when multiple muscle groups allow antagonist pairing; the response then carries structureReason. Keys created after 2026-08-19 default to auto; older keys default to straight. straight (default): classic straight sets, unchanged output. superset: exercises are paired into blocks (group "A", "B", ... with groupType and groupPosition on each exercise), short rest inside the pair (supersetRestSeconds), full rest after it; pairs mix muscle groups where possible. circuit: all main exercises form one circuit performed for rounds rounds - each exercise carries sets=rounds, restSeconds is the hop between stations (stationRestSeconds), and roundRestSeconds separates rounds.

roundsinteger

Circuit rounds (structure=circuit only).

includeWarmupboolean

Prepends a warmup block of bodyweight stretches, mobility work, and light cardio. Default true; set to false to omit. Warmup exercises count toward your monthly exercise cap.

warmupCountinteger

Number of warmup exercises. Only applied when includeWarmup is not false.

includeCooldownboolean

Appends a cooldown block of bodyweight stretches and mobility work at the end of the session. Default true; set to false to omit. Cooldown exercises count toward your monthly exercise cap.

cooldownCountinteger

Number of cooldown exercises. Only applied when includeCooldown is not false.

includeVideosboolean

Whether to include video URLs. When omitted, the default depends on your API key: keys created before 2026-07-07 default to true, newer keys default to false (browse mode). Pass includeVideos=true when you want playable videos - the returned exercises then count toward your monthly cap. Thumbnails are returned either way on this endpoint, on every plan.

Response

Generated workout. When the monthly exercise cap is exceeded, exercises not previously accessed will have video properties removed entirely. A _warning object is included with details.

Example response

{
  "data": {
    "exercises": [
      {
        "exercise": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "title": "Barbell Bench Press",
          "slug": "barbell-bench-press",
          "description": "A compound chest exercise performed lying on a flat bench.",
          "instructions": [
            "Lie on a flat bench with feet flat on the floor",
            "Grip the barbell slightly wider than shoulder width",
            "Lower the bar to mid-chest",
            "Press the bar back up to full arm extension"
          ],
          "importantPoints": [
            "Keep your back flat on the bench",
            "Do not bounce the bar off your chest"
          ],
          "muscleGroup": "chest",
          "secondaryMuscles": [
            "triceps",
            "shoulders"
          ],
          "muscleGroups": [
            "chest",
            "middle_chest",
            "pectoralis_major",
            "front_deltoids",
            "triceps",
            "core"
          ],
          "equipment": "barbell",
          "category": "compound",
          "difficulty": "intermediate",
          "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
          "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
          "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
          "thumbnails": {
            "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
            "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
            "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
            "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
            "original": "https://ymove.app/api/v2/thumbnail/video-id"
          },
          "videoDurationSecs": 12,
          "exerciseType": [
            "strength"
          ],
          "hasVideo": true,
          "hasVideoWhite": true,
          "hasVideoGym": false,
          "videos": [
            {
              "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88",
              "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
              "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
              "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
              "thumbnails": {
                "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
                "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
                "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
                "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
                "original": "https://ymove.app/api/v2/thumbnail/video-id"
              },
              "tag": "white-background",
              "orientation": "landscape",
              "isPrimary": true
            }
          ]
        }
      }
    ],
    "warmup": [
      {
        "exercise": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "title": "Barbell Bench Press",
          "slug": "barbell-bench-press",
          "description": "A compound chest exercise performed lying on a flat bench.",
          "instructions": [
            "Lie on a flat bench with feet flat on the floor",
            "Grip the barbell slightly wider than shoulder width",
            "Lower the bar to mid-chest",
            "Press the bar back up to full arm extension"
          ],
          "importantPoints": [
            "Keep your back flat on the bench",
            "Do not bounce the bar off your chest"
          ],
          "muscleGroup": "chest",
          "secondaryMuscles": [
            "triceps",
            "shoulders"
          ],
          "muscleGroups": [
            "chest",
            "middle_chest",
            "pectoralis_major",
            "front_deltoids",
            "triceps",
            "core"
          ],
          "equipment": "barbell",
          "category": "compound",
          "difficulty": "intermediate",
          "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
          "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
          "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
          "thumbnails": {
            "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
            "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
            "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
            "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
            "original": "https://ymove.app/api/v2/thumbnail/video-id"
          },
          "videoDurationSecs": 12,
          "exerciseType": [
            "strength"
          ],
          "hasVideo": true,
          "hasVideoWhite": true,
          "hasVideoGym": false,
          "videos": [
            {
              "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88",
              "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
              "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
              "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
              "thumbnails": {
                "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
                "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
                "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
                "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
                "original": "https://ymove.app/api/v2/thumbnail/video-id"
              },
              "tag": "white-background",
              "orientation": "landscape",
              "isPrimary": true
            }
          ]
        }
      }
    ],
    "cooldown": [
      {
        "exercise": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "title": "Barbell Bench Press",
          "slug": "barbell-bench-press",
          "description": "A compound chest exercise performed lying on a flat bench.",
          "instructions": [
            "Lie on a flat bench with feet flat on the floor",
            "Grip the barbell slightly wider than shoulder width",
            "Lower the bar to mid-chest",
            "Press the bar back up to full arm extension"
          ],
          "importantPoints": [
            "Keep your back flat on the bench",
            "Do not bounce the bar off your chest"
          ],
          "muscleGroup": "chest",
          "secondaryMuscles": [
            "triceps",
            "shoulders"
          ],
          "muscleGroups": [
            "chest",
            "middle_chest",
            "pectoralis_major",
            "front_deltoids",
            "triceps",
            "core"
          ],
          "equipment": "barbell",
          "category": "compound",
          "difficulty": "intermediate",
          "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
          "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
          "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
          "thumbnails": {
            "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
            "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
            "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
            "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
            "original": "https://ymove.app/api/v2/thumbnail/video-id"
          },
          "videoDurationSecs": 12,
          "exerciseType": [
            "strength"
          ],
          "hasVideo": true,
          "hasVideoWhite": true,
          "hasVideoGym": false,
          "videos": [
            {
              "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88",
              "videoUrl": "https://vz-xxx.b-cdn.net/video-id/play_720p.mp4?token=...",
              "videoHlsUrl": "https://vz-xxx.b-cdn.net/video-id/playlist.m3u8?token=...",
              "thumbnailUrl": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
              "thumbnails": {
                "default": "https://ymove.app/api/v2/thumbnail/video-id?crop=default",
                "square": "https://ymove.app/api/v2/thumbnail/video-id?crop=square",
                "portrait": "https://ymove.app/api/v2/thumbnail/video-id?crop=portrait",
                "landscape": "https://ymove.app/api/v2/thumbnail/video-id?crop=landscape",
                "original": "https://ymove.app/api/v2/thumbnail/video-id"
              },
              "tag": "white-background",
              "orientation": "landscape",
              "isPrimary": true
            }
          ]
        }
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.