# Get a storyboard preview

`GET https://api.cream-ai.de/api/v1/films/{id}/storyboard-preview`

Returns a storyboard preview of the film: without `preview_id` the newest one, otherwise the one with this id (`result.id` of the operation). `status`: `queued`, `rendering`, `ready`, `failed` or `expired` (previews are kept for a limited time, see `expires_at`). `scenes` shows the time range and state of each scene in the preview (`current`, `stale` = from an earlier version, `missing` = not rendered yet). `current` is `true` if every scene is up to date and the preview belongs to the current storyboard. Download the file with `file_url` as soon as `status` is `ready`.

Scopes: `films:read`, `previews:read`

## Parameters

- `id` (path, required): Id of the film (id from POST /films or GET /films).
- `preview_id` (query): Id of the preview (result.id of the operation). Default: the newest preview of the film.

## Returns

- 200: The storyboard preview.

## Errors

- 400: Invalid request (invalid_request, invalid_json, invalid_cursor, idempotency_key_required, invalid_idempotency_key, parent_not_found, max_depth_exceeded, narration_too_long, user_not_in_company, template_not_found, category_not_found, feedback_kind_unsupported, upload_not_found).
- 401: Missing, malformed, revoked or expired API key (unauthorized).
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 404: The film or the preview was not found, or the film has no preview yet (not_found).
- 429: Too many requests (rate_limited).
- 500: Internal error (internal). Quote the request id when you contact support.
- 503: Temporarily unavailable (service_unavailable). Retry later (after Retry-After seconds, if sent).

## Example request

```sh
curl "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/storyboard-preview" \
  -H "Authorization: Bearer $MINT_API_KEY"
```

## Example response (200)

```json
{
  "object": "storyboard_preview",
  "id": "pv_8c1e4a7d2b5f9e3c6a0d1b4e7f2a5c8d",
  "film_id": "k7m2xq9v4t8n1b5r3c6d0wza",
  "status": "ready",
  "storyboard_version": 1,
  "current": true,
  "duration_s": 181.2,
  "fps": 25,
  "resolution": "1280x720",
  "bytes": 18342210,
  "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "watermark": true,
  "scenes": [
    {
      "nr": 1,
      "start_s": 0,
      "end_s": 12.4,
      "state": "current"
    },
    {
      "nr": 2,
      "start_s": 12.4,
      "end_s": 25.9,
      "state": "current"
    }
  ],
  "file_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/storyboard-preview/file?preview_id=pv_8c1e4a7d2b5f9e3c6a0d1b4e7f2a5c8d",
  "created_at": "2026-11-10T08:25:00Z",
  "ready_at": "2026-11-10T08:27:41Z",
  "expires_at": "2026-11-24T08:27:41Z"
}
```