---
title: "Finalize a direct upload (trigger processing after the bytes are PUT)"
method: POST
path: "/v1/media/{id}/finalize"
tags: ["media"]
---

# Finalize a direct upload (trigger processing after the bytes are PUT)

`POST /v1/media/{id}/finalize`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/media/{id}/finalize`
- 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

## Request body

- MediaFinalizeRequest: POST /media/:id/finalize body — optional declared audioRole.
  - `audioRole` 'vo' | 'music' | 'sfx' | 'ambience': Declared audio role: 'vo' (narration), 'music' (bed that ducks under speech), 'sfx' (one-shot hit), 'ambience' (a bed that HOLDS under VO — never ducks).

## Response `200`

Ingest triggered.

- MediaFinalizeResponse: POST /media/:id/finalize response: ingest triggered (audio/video → processing) or the item is immediately ready (image/asset → complete).
  - `id` string, required
  - `status` 'processing' | 'complete', required
  - `processingPhase` string, required

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `500`: Internal error.

---

[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)