---
title: "Render one component preview"
method: POST
path: "/v1/projects/{id}/component-preview"
tags: ["evidence"]
---

# Render one component preview

`POST /v1/projects/{id}/component-preview`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/projects/{id}/component-preview`
- 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: `projects:write`)
  - API key in header `PAYMENT-SIGNATURE`

Queue a preview of ONE org-installed native (version 4) component: a PNG of its middle frame, rendered by the same HyperFrames runtime as the production render. Returns a jobId — wait_job(kind='preview') for the image. Compile/runtime failures land on the job terminal with the sanitized author-fixable message.

## Path parameters

- `id` string, required

## Request body

- ComponentPreviewRequest
  - `componentId` string, required
  - `params` object
  - `assets` object: Component asset-slot name to org mediaId. Every required manifest slot must be bound.
  - `width` integer: Exact width of a supported composition format. Width and height must match one aspect ratio/resolution pair; omitted values use the project format.
  - `height` integer: Exact height paired with width for a supported composition format.
  - `fps` union: Preview frame rate: 24, 25, 30, or 60. When omitted, uses the project's format.
    - 24
    - 25
    - 30
    - 60
  - `durationInFrames` integer: Preview frame count. When omitted, uses the component's declared duration; required if the component has none.

## Response `202`

Preview job queued.

- JobEnqueueResponse
  - `jobId` string, required: Poll GET /v1/jobs/{jobId} / wait_job until terminal.
  - `jobKey` string, required: Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt.
  - `kind` string, required: Job family, e.g. `verify` | `preview` | `brand_kit_extract`.
  - `status` 'running' | 'succeeded' | 'cancelled', required: running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.

## 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.
- `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)