---
title: "Trigger standalone subject/face detection"
method: POST
path: "/v1/media/{id}/detect-subjects"
tags: ["media"]
---

# Trigger standalone subject/face detection

`POST /v1/media/{id}/detect-subjects`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/media/{id}/detect-subjects`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:write`)
  - API key in header `PAYMENT-SIGNATURE`

Required permission: media:write

## Path parameters

- `id` string, required

## Query parameters

- `detector` 'face' | 'person'

## Response `202`

Detection claimed. `alreadyExisted:true` means this exact detection was already pending or ready — nothing was dispatched and nothing will be charged.

- SubjectDetectionTriggerResponse: POST /media/:id/detect-subjects response — the claimed perception fact.
  - `factId` string, required: Opaque identifier for the derived fact.
  - `status` 'pending' | 'ready' | 'failed', required: State of the fact right now. `ready` with `alreadyExisted` means the detection was already computed and is available immediately.
  - `quotedUsd` number, required: The server's price for this detection, in USD, quoted from the source duration. Zero is charged when `alreadyExisted` is true.
  - `alreadyExisted` boolean, required: True when this exact detection was already pending or ready. Nothing was dispatched and nothing will be charged — the same fact is served twice for one price.

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required — billing_required or x402 payment_*.
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `409`: Conflict — stale_etag / idempotency_conflict / suggestions_already_complete.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)