# Create a project

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

- Scope: `projects.write`
- Cost: project quota

Create an empty 16:9, 1920x1080, 30 fps project, optionally applying a first batch of commands. Counts against the plan's project limit.

### Body

- `name` (string, optional, default `Untitled Project`): Up to 80 characters.
- `commands` (array of objects, optional): Optional commands to apply straight after creation, with the same rules as [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands). If they fail, the project is still created.

## Response

Returns `201`.

### Response fields

- `project` (object): The new project, summary view.
  - `id` (string): Project id.
  - `name` (string): Project name.
  - `createdAt` (string): ISO 8601 time.
  - `updatedAt` (string): ISO 8601 time.
  - `durationSec` (number): End of the last clip, in seconds.
  - `clipCount` (integer): Number of clips on the timeline.
  - `settings` (object): Output settings.
    - `aspectRatio` (string): For example `16:9`.
    - `width` (integer): Pixels.
    - `height` (integer): Pixels.
    - `fps` (number): Frames per second.
    - `background` (string): CSS colour.
  - `workspace` (object or null): The workspace it is filed in: `{ id, name }`, or `null`.
- `results` (array): Only when you sent `commands`. See Apply commands.

> **Tip: With a test key.** Test keys create real projects. Use a dedicated test project.

## 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 |
| --- | --- | --- |
| 402 | [`quota_exceeded`](https://developer.vidmoat.com/developer/docs/errors#quota_exceeded) | The plan's project limit is reached. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/projects \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My first API edit"}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/projects', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My first API edit',
  }),
});
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

res = requests.post(
    "https://api.vidmoat.com/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "name": "My first API edit",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "project": {
    "id": "cm1abc",
    "name": "Launch teaser",
    "createdAt": "2026-09-30T10:00:00.000Z",
    "updatedAt": "2026-10-02T09:00:00.000Z",
    "durationSec": 12.5,
    "clipCount": 4,
    "settings": { "aspectRatio": "9:16", "width": 1080, "height": 1920, "fps": 30, "background": "#000000" },
    "workspace": null
  }
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/projects/create-project
Previous: [List projects](https://developer.vidmoat.com/developer/docs/api/projects/list-projects.md)
Next: [Get a project](https://developer.vidmoat.com/developer/docs/api/projects/get-project.md)
All documentation: https://developer.vidmoat.com/llms-full.txt