# Build a storyboard

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

- Scope: `ai.agent`
- Cost: agent steps, quoted per scene

Build the board on the server with the editing agent, one scene at a time. Each scene is its own run held to its card's requirements, with its own review; its verdict is written to the scene. Built scenes are skipped, so calling again carries on.

> **Note.** Needs a plan with server runs (Creator and up) with server runs turned on. On other plans the board builds in the editor (Build board), and this endpoint answers with the editor link. `quoteOnly: true` returns the quote and charges nothing.

### Path parameters

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

### Body

- `sceneIds` (array of strings, optional): Only these scenes. Default: every unbuilt scene.
- `maxCredits` (integer, optional): Refuse a board quoted above this, and stop between scenes when the next would pass it.
- `quoteOnly` (boolean, optional, default `false`): Return the quote only.

## Response

Returns `200`.

### Response fields

- `boardRunId` (string): Poll GET /v1/storyboard-runs/{id}.
- `sceneId` (string): The scene building first.
- `estimate` (object): Steps and credits per scene.

## 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. |
| 402 | [`plan_required`](https://developer.vidmoat.com/developer/docs/errors#plan_required) | The plan has no server runs; build it in the editor instead (`editorUrl`). |
| 409 | [`conflict`](https://developer.vidmoat.com/developer/docs/errors#conflict) | No board, every scene built, server runs turned off, or a run is already going on the project. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `maxCredits` is below the quote or out of range. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/projects/$ID/storyboard/runs \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxCredits":60}'
```

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

const res = await fetch(`https://api.vidmoat.com/v1/projects/${ID}/storyboard/runs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    maxCredits: 60,
  }),
});
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/runs",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "maxCredits": 60,
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

---

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