# Create a storyboard

`POST https://api.vidmoat.com/v1/projects/{id}/storyboard`

- Scope: `projects.write`
- Cost: Free

Start a board from exactly one of: a template id (needs an empty project), a script (one paragraph becomes one scene, split by blank lines), or a list of scenes. Scenes with a target length get a placeholder slot.

> **Note.** Limits: 40 scenes, 2000 characters a script. Over a limit the call is refused and nothing is saved; nothing is ever trimmed to fit.

### Path parameters

- `id` (string, required): The project id.

### Body

- `from` (object, required): `{ template }`, `{ script }` or `{ scenes }`.
- `aspectRatio` (string, optional): 16:9, 9:16, 1:1, 4:5, 4:3 or 21:9.
- `replace` (boolean, optional, default `false`): Replace an existing board; its clips stay as board-level clips.

## Response

Returns `200`.

### Response fields

- `created` (boolean): Always true.
- `scenes` (array): As GET /v1/projects/{id}/storyboard.

## 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 |
| --- | --- | --- |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | No such project, or it is not yours. The two are indistinguishable on purpose. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `from` names none or several sources, or a scene breaks a limit. |
| 409 | [`conflict`](https://developer.vidmoat.com/developer/docs/errors#conflict) | The project already has a board (pass `replace`), or a template was asked for a project with clips. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/projects/$ID/storyboard \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":{"script":"Stop scrolling.\n\nMost cold brew tastes burnt.\n\nOurs steeps for 18 hours."}}'
```

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

const res = await fetch(`https://api.vidmoat.com/v1/projects/${ID}/storyboard`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: {
      script: 'Stop scrolling.
  
  Most cold brew tastes burnt.
  
  Ours steeps for 18 hours.',
    },
  }),
});
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(
    f"https://api.vidmoat.com/v1/projects/{ID}/storyboard",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "from": {
        "script": "Stop scrolling.\n\nMost cold brew tastes burnt.\n\nOurs steeps for 18 hours.",
      },
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

---

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