# Cancel a film

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

Cancels a film ordered through the API, also while mint is planning or producing it automatically, until the storyboard is ready. Running planning and production are stopped; costs that already occurred stay. Once the storyboard (or the film) is ready, the film can no longer be cancelled through the API: `409 not_cancellable` with `details.reason` (for example `not_api_film` for projects created in mint, `other_client` if another API access ordered the film, `storyboard_ready`). Only the API access that ordered the film can cancel it, unless that access was revoked or expired. Cancelling again returns `200` with the cancelled film. A cancelled film frees its `video_key` and `version`: the same order then creates a new film.

Scopes: `films:write`

## Parameters

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

## Request body

- `reason` (nullable string): Optional reason (at most 500 characters) for the cancellation.

## Returns

- 200: The cancelled film.

## 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: Not found (not_found).
- 409: Conflict (category_exists, external_key_exists, external_key_conflict, category_limit_reached, idempotency_in_progress, version_conflict, previous_version_creating, film_deleted, not_cancellable, file_unavailable, storyboard_not_ready, storyboard_not_current, timeline_outdated, preview_in_progress, preview_not_ready, preview_unsupported, feedback_queue_full, feedback_not_cancellable, feedback_not_retryable, feedback_busy, revision_locked, film_not_ready, film_busy, no_open_comments, comments_not_open, correction_in_progress, upload_quota_exceeded, film_cancelled).
- 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/cancel" \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Lesson was removed from the course."
  }'
```

## Example response (200)

```json
{
  "object": "film",
  "id": "k7m2xq9v4t8n1b5r3c6d0wza",
  "title": "Lesson 3: Market segmentation",
  "status": "cancelled",
  "stage": "cancelled",
  "attention_required": false,
  "notice": null,
  "source": "api",
  "automation": "storyboard",
  "video_key": "MKT101-lesson-03",
  "version": "1.0",
  "previous_version_id": null,
  "is_latest_approved_version": true,
  "language": "de",
  "template": "lesson-standard",
  "settings": {
    "format": "16x9",
    "style_id": "b6ed57e1-2c4f-4b8a-9d3e-6f1a0c2b7e45",
    "style_revision": 4,
    "brand_id": "brand-northwind-x7k2p9",
    "voice_id": "Xb7hH8MSUJpSbSDYk0k2",
    "voice_name": "Clara",
    "narration_mode": "verbatim",
    "tempo": "presenting",
    "freedom": 40,
    "video_share": 25,
    "target_duration_s": 180
  },
  "category": {
    "object": "category",
    "id": "rz3p8w1d6c0b",
    "name": "MKT101 Marketing basics",
    "external_key": "MKT101",
    "parent": {
      "id": "mk7t2q9x4v1n",
      "name": "Marketing",
      "external_key": "MKT"
    }
  },
  "requested_by": {
    "kind": "user",
    "email": "anna.schmidt@example.edu",
    "name": "Anna Schmidt"
  },
  "metadata": {
    "course_id": "MKT101",
    "lesson": 3
  },
  "approval": null,
  "cancelled_at": "2026-11-10T08:05:10Z",
  "created_at": "2026-11-10T08:00:00Z",
  "updated_at": "2026-11-10T08:05:10Z",
  "app_url": "https://app.cream-ai.de/editorial/k7m2xq9v4t8n1b5r3c6d0wza",
  "file_url": null,
  "subtitles_url": null,
  "revisions": [],
  "latest_revision": null
}
```