---
title: "Create a 'find-best-thumbnails' job"
method: POST
path: "/robots/v0/jobs/find-best-thumbnails"
tags: ["Find Best Thumbnails (v0)"]
deprecated: true
---

# Create a 'find-best-thumbnails' job

`POST /robots/v0/jobs/find-best-thumbnails`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v0/jobs/find-best-thumbnails`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

> **Deprecated.**

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.

## Request body

- CreateFindBestThumbnailsJobRequestV0
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` FindBestThumbnailsJobParametersV0, required
    - `asset_id` string, required: The Mux asset ID of the video to find thumbnails for.
    - `max_thumbnails` integer: Maximum number of candidate thumbnails to return (1-5). Defaults to 5.
    - `output_steering` FindBestThumbnailsOutputSteeringV0: Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output.
      - `scope` object: Optional sampling window in seconds on the original asset timeline, normalized inward to whole-millisecond half-open bounds. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned thumbnail timestamps remain absolute asset timestamps.
        - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
        - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
      - `selection_strategy` 'face_or_action' | 'clean_composition' | 'high_contrast' | 'brand_safe' | 'campaign_thumbnail': Best-effort guidance for what kind of thumbnail candidate should score highest.
      - `looking_for` string: Open-ended description of what the user is explicitly looking for in candidate thumbnails. Best-effort guidance only.
      - `audience` string: Intended audience used as best-effort scoring guidance. Does not change the output schema.
      - `campaign_style` string: Short description of the campaign/channel thumbnail style to prefer when supported by the frame.
      - `scoring_priorities` FindBestThumbnailsScoringPriorityV0[]: Rubric criteria to emphasize in close calls. Best-effort guidance only.
    - `update_asset_thumbnail` boolean: When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings.

## Response `202`

Find best thumbnails job queued

- FindBestThumbnailsJobResponseV0
  - `data` FindBestThumbnailsJobV0, required
    - `id` string, required: Unique job identifier.
    - `passthrough` string: Arbitrary string supplied at creation, returned as-is.
    - `units_consumed` integer, required: Number of Mux AI units consumed by this job.
    - `directive` JobDirectiveContextV0: The directive run that dispatched this job. Absent for jobs created via direct API POST.
      - `id` string, required: ID of the directive that dispatched this job.
      - `run_id` string, required: ID of the specific directive run that dispatched this job.
    - `created_at` integer, required: Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required: Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state).
    - `workflow` 'find-best-thumbnails', required
    - `parameters` FindBestThumbnailsJobParametersV0, required
      - `asset_id` string, required: The Mux asset ID of the video to find thumbnails for.
      - `max_thumbnails` integer: Maximum number of candidate thumbnails to return (1-5). Defaults to 5.
      - `output_steering` FindBestThumbnailsOutputSteeringV0: Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output.
        - `scope` object: Optional sampling window in seconds on the original asset timeline, normalized inward to whole-millisecond half-open bounds. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned thumbnail timestamps remain absolute asset timestamps.
          - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
          - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
        - `selection_strategy` 'face_or_action' | 'clean_composition' | 'high_contrast' | 'brand_safe' | 'campaign_thumbnail': Best-effort guidance for what kind of thumbnail candidate should score highest.
        - `looking_for` string: Open-ended description of what the user is explicitly looking for in candidate thumbnails. Best-effort guidance only.
        - `audience` string: Intended audience used as best-effort scoring guidance. Does not change the output schema.
        - `campaign_style` string: Short description of the campaign/channel thumbnail style to prefer when supported by the frame.
        - `scoring_priorities` FindBestThumbnailsScoringPriorityV0[]: Rubric criteria to emphasize in close calls. Best-effort guidance only.
      - `update_asset_thumbnail` boolean: When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status.
    - `errors` JobErrorV0[]: Error details. Present when status is 'errored'.
      - `type` string, required: Stable public error category identifier.
      - `message` string, required: Human-readable public error message.
      - `retryable` boolean: Whether retrying this job may resolve the error.
    - `resources` ResourcesV0: Related Mux resources linked to this job.
      - `assets` SlimlineAssetV0[], required: Mux assets associated with this job.
        - `id` string, required: Mux asset ID.
        - `meta` object: Mux asset metadata, if available.
          - `title` string: Asset title from Mux metadata.
          - `creator_id` string: Creator identifier from Mux metadata.
          - `external_id` string: External identifier from Mux metadata.
        - `passthrough` string: Passthrough string from the Mux asset.
        - `_links` object, required: Hypermedia links for the asset.
          - `self` object, required
            - `href` string, required: URL to the Mux asset resource.
    - `outputs` FindBestThumbnailsJobOutputsV0: Workflow results. Present when status is 'completed'.
      - `best_thumbnails` object[], required: Selected candidate thumbnails from the original asset timeline, ordered best to worst by overall quality score.
        - `timestamp_ms` integer, required: Absolute frame timestamp in whole milliseconds on the original asset timeline.
        - `subscores` object, required: Per-category quality scores.
          - `focus` number, required: Sharpness and focus quality score (0-1).
          - `face_or_action` number, required: Presence of faces or dynamic action score (0-1).
          - `composition` number, required: Visual composition and framing quality score (0-1).
          - `contrast_color` number, required: Color contrast and vibrancy score (0-1).
          - `brand_fit` number, required: Alignment with brand guidelines score (0-1).
        - `overall` number, required: Overall quality score from 0 to 1.
        - `description` string, required: AI-generated description of the frame content.
        - `alt_text` string: Suggested alternative text for the candidate thumbnail image, suitable for use with the thumbnail URL in an accessible UI.
      - `asset_updates` FindBestThumbnailsAssetUpdateOutcomesV0: Recorded asset thumbnail update outcome. Omitted when no outcome was recorded, including historical jobs.
        - `thumbnail` FindBestThumbnailsThumbnailAssetUpdateV0
          - `status` 'updated' | 'failed', required: Outcome of the requested asset thumbnail update.

## Other responses

- `400`: Malformed or missing JSON request body, or invalid request parameters
- `401`: Missing or invalid Mux credentials
- `403`: Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.
- `409`: A job with the same workflow and parameters is already pending or processing for this environment.
- `422`: Asset not found, not a video asset, missing public or signed playback ID, or scope does not contain a whole-millisecond interval within the asset
- `500`: Server error

## Changes

- **2026-10-26** `151835caff06`: 1 info
  - endpoint deprecated
- **2026-10-19** `7e2e5079412d`: 1 breaking, 1 warning, 5 info
  - added `#/components/schemas/OutputSteeringScopeV0` to the `parameters/output_steering/scope` request property `allOf` list
  - removed `#/components/schemas/OutputSteeringScope` from the `parameters/output_steering/scope` request property `allOf` list
  - api operation id `create-find-best-thumbnails-job` removed and replaced with `create-find-best-thumbnails-job-v0`
  - api tag `Find Best Thumbnails (v0)` added
  - …3 more
- **2026-10-08** `296f0b01bb84`: 2 breaking, 14 info
  - request body became required
  - the `parameters/asset_id` request property's minLength was increased from `0` to `1`
  - the `max_thumbnails` request property default value `5` was added
  - added the non-success response with the status `400`
  - …12 more
- **2026-09-17** `68a2dd0743bf`: 1 info
  - added the non-success response with the status `409`
- **2026-08-12** `5b4b3133f27d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v0/jobs/find-best-thumbnails/post.md)

---

[API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)