Find Scenes (v0)

Create a 'find-scenes' job

Changed on

Deprecated: use POST /robots/v1/jobs/analyze-structure instead. Creates a new job that segments a Mux video asset into ordered scenes using storyboard-backed generated shots for shot-level visual evidence, combined with transcript cues when available. If the asset has no generated shots, the job generates them on demand and waits for completion — they do not need to exist beforehand. Optional output steering can restrict execution to a time scope in seconds and guide segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy without changing the response schema. Scoped results retain absolute timestamps on the original asset timeline.

post/robots/v0/jobs/find-scenes

Request

  • Base URL
    https://api.mux.com
  • Auth
    • HTTP basic
    • or HTTP bearer

Request body

passthroughstring

Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.

Example request

{
  "parameters": {
    "asset_id": "mux_asset_123abc",
    "language_code": "en",
    "min_scenes": 4,
    "min_scene_duration_ms": 15000,
    "output_steering": {
      "scope": {
        "start_time": 30,
        "end_time": 180
      },
      "segmentation_strategy": "editorial_beats",
      "title_style": "descriptive",
      "narration_detail": "balanced"
    }
  }
}

Response

Find scenes job queued

Example response

{
  "data": {
    "parameters": {
      "asset_id": "mux_asset_123abc",
      "language_code": "en",
      "min_scenes": 4,
      "min_scene_duration_ms": 15000,
      "output_steering": {
        "scope": {
          "start_time": 30,
          "end_time": 180
        },
        "segmentation_strategy": "editorial_beats",
        "title_style": "descriptive",
        "narration_detail": "balanced"
      }
    },
    "resources": {
      "assets": [
        {
          "id": "abc123asset",
          "meta": {
            "title": "My Video",
            "creator_id": "user123",
            "external_id": "ext456"
          },
          "_links": {
            "self": {
              "href": "/video/v1/assets/abc123asset"
            }
          }
        }
      ]
    },
    "outputs": {
      "scenes": [
        {
          "start_ms": 0,
          "end_ms": 15000,
          "title": "Opening Remarks",
          "cues": [
            {
              "start_ms": 500,
              "end_ms": 5000,
              "text": "Welcome everyone to today's session."
            }
          ],
          "audible_narrative": "The host introduces the topic and welcomes the audience.",
          "notable_audible_concepts": [
            "session introduction overview",
            "welcome and context"
          ],
          "visual_narrative": "A speaker stands at a podium in front of a large screen.",
          "shot_count": 2
        }
      ]
    }
  }
}

Changes

    • info

      endpoint deprecated

    • breaking

      added to the // request property allOf list

    • breaking

      added to the // request property allOf list

    • breaking

      added to the // request property allOf list

    • warning

      removed from the // request property allOf list

    • warning

      removed from the // request property allOf list

    • warning

      removed from the // request property allOf list

    • info

      api operation id create-find-scenes-job removed and replaced with create-find-scenes-job-v0

    • info

      api tag Find Scenes (v0) added

    • info

      api tag Find Scenes removed

    • info

      added to the /// response property allOf list for the response status

    • info

      added to the /// response property allOf list for the response status

    • info

      added to the /// response property allOf list for the response status

    • info

      removed from the /// response property allOf list for the response status

    • info

      removed from the /// response property allOf list for the response status

    • info

      removed from the /// response property allOf list for the response status