# Request a storyboard preview (costs credits)

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

Has mint create a storyboard preview of the film: one MP4 (1280x720) with the current scene clips in film order, the voice-over and a visible watermark „PREVIEW · Scene n“. It is not the finished film and never replaces the approval in mint. The preview is optional. Each new preview costs credits according to the mint price list (currently 100 credits); mint books them on the company in the name of the user from `user_email` of the order, after the preview is ready. A failed preview is not charged. When requesting, the company must have enough credits for this preview and for all of its previews that are still being created or not charged yet; otherwise the response is `402 insufficient_credits` with `details.required_credits` (the credits needed for all of them) and nothing is created. The response is an operation (`202 Accepted`, `Location: /api/v1/operations/{id}`). Poll it until `status` is `succeeded`; `result.url` then points to the preview. If a ready preview of exactly the same storyboard state exists, the response is `200` with an operation that has already `succeeded` and `reused: true`; it points to that preview and is not charged again. If the same state is being created right now, the response is `202` with `reused: true`. Scenes that are not up to date are shown as „outdated“ or as a dark panel „is still being rendered“. With `require_current: true` the request is rejected with `409 storyboard_not_current` (`details.scenes`) as long as a scene is not up to date. `409 storyboard_not_ready`: the film has no storyboard yet. `409 preview_in_progress` (`details.operation_id`): a preview of another state of this film is still being created; retry later. `409 preview_unsupported`: previews are not available for this kind of film. `409 film_cancelled`: the film was cancelled through the API; existing previews can still be read. `503` with `details.feature` `storyboard_preview`: previews are switched off right now. Rejections with a passing reason (`storyboard_not_ready`, `preview_in_progress`, `insufficient_credits`) are not stored under the Idempotency-Key: a retry with the same key runs again. The operation stays bound to its key: the same key with another request returns `422 idempotency_mismatch`, also after 24 hours.

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

## Parameters

- `id` (path, required): Id of the film (id from POST /films or GET /films).
- `Idempotency-Key` (header, required): Unique key of this write request (1–128 visible ASCII characters, e.g. a UUID). Retries with the same key return the stored response.

## Request body

- `require_current` (boolean): true: only create the preview if every scene is up to date (otherwise 409 storyboard_not_current). Default false: outdated and missing scenes are marked in the preview.

## Returns

- 200: A ready preview of the same storyboard state exists (status succeeded, reused: true, not charged again), or the operation of this Idempotency-Key has already finished.
- 202: The preview is being created (or the same state is already being created, reused: true). Poll the operation from Location.

## 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).
- 402: The company does not have enough credits for a preview (insufficient_credits, details.required_credits). Nothing was created; not stored under the Idempotency-Key.
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 404: Not found (not_found).
- 409: No storyboard yet (storyboard_not_ready), scenes not up to date with require_current (storyboard_not_current, details.scenes), a preview of another state is being created (preview_in_progress, details.operation_id), previews not available for this film (preview_unsupported), the film was cancelled through the API (film_cancelled), or a request with this Idempotency-Key is still running (idempotency_in_progress).
- 413: Request body too large (payload_too_large).
- 415: Request body is not JSON (unsupported_media_type).
- 422: Idempotency-Key reused with a different request (idempotency_mismatch).
- 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 -X POST "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/storyboard-preview" \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Example response (202)

```json
{
  "object": "operation",
  "id": "op_4d9b2e7a1c6f3d8b5e0a2c7f9b4d1e6a",
  "type": "storyboard.preview",
  "status": "queued",
  "created_at": "2026-11-10T08:25:00Z",
  "updated_at": "2026-11-10T08:25:00Z",
  "result": null,
  "error": null,
  "reused": false
}
```