# CueFrame video editing and rendering API

> Create editable video projects, manage media and captions, and render MP4s through a hosted REST API. The TypeScript SDK uses the same public contract.

## Authentication and requirements

Create an API key in [your CueFrame account](https://app.cueframe.ai). Store it in `CUEFRAME_API_KEY` on your server, outside browser bundles. Requests use `Authorization: Bearer YOUR_API_KEY` and the base URL `https://api.cueframe.ai`.

Check account access and credit entitlements before metered operations:

```bash
curl --fail-with-body https://api.cueframe.ai/v1/me \
  -H "Authorization: Bearer $CUEFRAME_API_KEY"
```

The TypeScript SDK requires Node.js 24 or newer: `npm install @cueframe/sdk`. See [SDK setup and account example](https://github.com/cueframe-ai/cueframe-mcp/blob/main/packages/sdk/README.md). Direct REST callers can use other languages.

## Run a complete example

Download [yosemite-api.mjs](https://cueframe.ai/code/yosemite-api.mjs) and follow the [source footage instructions](https://cueframe.ai/api#run). The standalone script requires Node.js 22 or newer:

```bash
node yosemite-api.mjs ./yosemite-peregrines.mp4
```

The script checks your account, uploads the original source, prepares an editable template project, waits for the first render, changes only the title using the composition's ETag, then saves and renders again. It downloads `phenomenal.mp4` and `extraordinary.mp4` and prints job IDs. Both renders and cloud processing are metered; check [pricing](https://cueframe.ai/pricing) first.

## Follow a render job

Rendering an existing project starts with `POST /v1/projects/{projectId}/renders`. Keep the returned `id`. To inspect that job without creating another render:

```bash
curl --fail-with-body \
  "https://api.cueframe.ai/v1/projects/$CUEFRAME_PROJECT_ID/renders/$CUEFRAME_RENDER_ID" \
  -H "Authorization: Bearer $CUEFRAME_API_KEY"
```

Set both IDs from the original request. Poll this GET while the job is `queued`, `pending` or `rendering`. On `complete`, use `outputUrl` to retrieve the video. On `error` or `cancelled`, inspect the returned details and stop; do not treat a failed job as a download-ready result. The downloadable example implements polling with a timeout.

## Handle failures and concurrent edits

Inspect the HTTP status and returned error before retrying. A 402 may indicate a payment requirement; it is not proof of invalid credentials. For 429, honor `Retry-After` when present. For an interrupted render request, inspect the known job before starting another; a new POST can create additional paid work.

Read a composition with GET and retain its ETag. Send that ETag in `If-Match` when saving with PUT. If another edit wins first, refetch and reconcile the changes rather than overwriting the project. The Yosemite script stops if its save is rejected.

## Contract and documentation

- [API reference](https://docs.cueframe.ai/docs/api): request fields, response schemas and job states.
- [Public OpenAPI](https://api.cueframe.ai/v1/openapi.json)
- [Versioned API contract](https://www.npmjs.com/package/@cueframe/api-contract)
- [SDK source and examples](https://github.com/cueframe-ai/cueframe-mcp/tree/main/packages/sdk)
- [CLI quickstart](https://cueframe.ai/cli.md)
- [Hosted MCP](https://cueframe.ai/mcp): the primary entry point for agent conversations.