Find Best Thumbnails (v0)

Create a 'find-best-thumbnails' job

Changed on

Deprecated: use POST /robots/v1/jobs/find-best-thumbnails instead. Creates a new job that samples thumbnails from a Mux Video asset, scores them with AI, and selects the best thumbnail candidates. Optional output_steering.scope hard-limits sampling to a time window expressed in seconds while returned timestamps stay absolute to the asset timeline. Other output steering can guide scoring strategy, explicit user intent, audience, and campaign style without changing the response schema.

post/robots/v0/jobs/find-best-thumbnails

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",
    "max_thumbnails": 3,
    "update_asset_thumbnail": true,
    "output_steering": {
      "scope": {
        "start_time": 30,
        "end_time": 180
      },
      "selection_strategy": "campaign_thumbnail",
      "scoring_priorities": [
        "composition",
        "brand_fit"
      ]
    }
  }
}

Response

Find best thumbnails job queued

Example response

{
  "data": {
    "id": "rjob_example",
    "workflow": "find-best-thumbnails",
    "status": "completed",
    "units_consumed": 100,
    "created_at": 1791302400,
    "updated_at": 1791302460,
    "parameters": {
      "asset_id": "mux_asset_123abc",
      "max_thumbnails": 1
    },
    "outputs": {
      "best_thumbnails": [
        {
          "timestamp_ms": 23000,
          "subscores": {
            "focus": 0.9,
            "face_or_action": 0.8,
            "composition": 0.9,
            "contrast_color": 0.8,
            "brand_fit": 0.7
          },
          "overall": 0.82,
          "description": "A presenter demonstrating the product against a clear background.",
          "alt_text": "Presenter holding the product toward the camera."
        }
      ]
    }
  }
}

Changes

    • info

      endpoint deprecated

    • breaking

      added to the // request property allOf list

    • warning

      removed from the // request property allOf list

    • info

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

    • info

      api tag Find Best Thumbnails (v0) added

    • info

      api tag Find Best Thumbnails removed

    • info

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

    • info

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