# Queue a render

`POST https://api.vidmoat.com/v1/renders`

- Scope: `render.write`
- Cost: export quota

Queue an export of a project's saved document. Resolution cap, watermark and concurrency come from the owner's plan.

### Body

- `projectId` (string, required): A project you own, with at least one clip.
- `format` (enum, optional, default `mp4`): Container. Any other value becomes `mp4`. One of `mp4`, `webm`, `gif`.
- `quality` (enum, optional, default `standard`): Encoder quality. Any other value becomes `standard`. One of `draft`, `standard`, `high`.
- `resolution` (enum, optional, default `full`): Half renders at half the project height. One of `full`, `half`.

## Response

Returns `202`.

### Response fields

- `render` (object): The job, `PENDING` at first.
  - `id` (string): Render job id.
  - `projectId` (string): The project rendered.
  - `status` (enum): Where the job is. One of `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`.
  - `progress` (integer): 0 to 100.
  - `format` (string): `mp4`, `webm` or `gif`.
  - `resolution` (string): `full` or `half`.
  - `quality` (string): `draft`, `standard` or `high`.
  - `url` (string or null): The download URL once `COMPLETED`.
  - `error` (string or null): Why it failed, when `FAILED`.
  - `createdAt` (string): ISO 8601 time.
  - `updatedAt` (string): ISO 8601 time.
- `applied` (object): What the plan decided: `{ resolution, watermark, priority }`, plus `maxHeight` and `cappedByPlan: true` when the plan capped the height.
- `poll` (string): The path to poll.

> **Tip: With a test key.** Test keys still check the project, then return a finished sample render (`status: "COMPLETED"`, `test: true`, a fixture `url`) without queueing anything or using your export allowance. The same request returns the same id.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `projectId` is missing, or the project has no clips. |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | No such project, or not yours. |
| 402 | [`quota_exceeded`](https://developer.vidmoat.com/developer/docs/errors#quota_exceeded) | Monthly exports used up, too many renders running at once for the plan, or the project uses media the plan cannot export. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/renders \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"'$ID'","format":"mp4","quality":"standard"}'
```

```js Node
const ID = 'YOUR_PROJECT_ID';

const res = await fetch('https://api.vidmoat.com/v1/renders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: ID,
    format: 'mp4',
    quality: 'standard',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

ID = "YOUR_PROJECT_ID"

res = requests.post(
    "https://api.vidmoat.com/v1/renders",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "projectId": ID,
      "format": "mp4",
      "quality": "standard",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "render": {
    "id": "clx9abc123", "projectId": "cm1abc", "status": "PENDING", "progress": 0,
    "format": "mp4", "resolution": "full", "quality": "standard",
    "url": null, "error": null,
    "createdAt": "2026-10-03T12:00:00.000Z", "updatedAt": "2026-10-03T12:00:00.000Z"
  },
  "applied": { "resolution": "full", "watermark": false, "priority": true },
  "poll": "/api/v1/renders/clx9abc123"
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/renders/create-render
Previous: [File a project](https://developer.vidmoat.com/developer/docs/api/workspaces/set-project-workspace.md)
Next: [List renders](https://developer.vidmoat.com/developer/docs/api/renders/list-renders.md)
All documentation: https://developer.vidmoat.com/llms-full.txt