---
title: "Convert storyboard document to timeline document"
method: POST
path: "/api/v1/storyboards/to-timeline"
tags: ["Storyboards"]
---

# Convert storyboard document to timeline document

`POST /api/v1/storyboards/to-timeline`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/storyboards/to-timeline`
- Auth: HTTP bearer

Converts a Kaitoi Storyboard Document v1 into a Kaitoi Timeline Document v1 without mutating any project. Storyboard shots become sequential timeline clips; URL, document, unresolved, and unsupported media references are skipped with warnings instead of being fetched.

## Headers

- `authorization` string, nullable

## Request body

- PublicStoryboardToTimelineRequest
  - `document` object, required: Kaitoi Storyboard Document v1 JSON to convert.
  - `name` string, nullable: Optional name for the generated Timeline Document.
  - `frameRate` integer: Timeline frame rate. Unsupported values normalize to 30.
  - `projectResolution` object, nullable: Optional timeline project resolution.
  - `defaultDuration` number, nullable: Fallback shot duration in seconds when a storyboard shot omits durationSeconds.

## Response `200`

Generated timeline document and non-fatal conversion warnings.

- PublicStoryboardToTimelineResponse
  - `document` object, required: Generated Kaitoi Timeline Document v1.
  - `summary` PublicTimelineSummary, required
    - `trackCount` integer, required: Number of tracks in the timeline.
    - `clipCount` integer, required: Number of clips in the timeline.
    - `durationSeconds` number, required: Timeline project duration in seconds.
  - `warnings` PublicStoryboardWarning[]: Non-fatal conversion warnings.
    - `code` string, required: Stable warning code.
    - `message` string, required: Human-readable warning message.
    - `path` string, required: Path to the affected storyboard document field.

## Other responses

- `400`: The storyboard document is invalid or cannot be converted.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `503`: The shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)