# The film object

A film ordered through the API. source is currently always api; app is reserved for projects created in mint, which v1 does not return yet.

## Attributes

- `object` (string, required):
- `id` (string, required): Id of the film in mint.
- `title` (string, required): Title as it is in mint now (people can change it there).
- `status` (enum, required): briefing: created in mint, nothing is running (for example with automation: none). in_production: mint is planning or producing the storyboard (or the film). storyboard_ready: the storyboard is ready for review in mint. With automation: storyboard the film stops here until a person continues in mint. film_ready: the film is rendered and waits for approval by a person in mint. approved: a person approved the film in mint. cancelled: the film was cancelled. New values may be added within v1. Values: `briefing`, `in_production`, `storyboard_ready`, `film_ready`, `approved`, `cancelled`.
- `stage` (nullable enum, required): Detailed stage as shown in the mint project list, or null if unknown. New values may be added within v1. Values: `briefing`, `style`, `voice`, `ready_to_plan`, `planning`, `storyboard_in_progress`, `storyboard_review`, `film_rendering`, `film_ready`, `approved`, `paused`, `error`, `cancelled`.
- `attention_required` (boolean, required): true if a person needs to act in mint (see notice).
- `notice` (nullable object, required): Why a person needs to act in mint, or null. Codes: production_paused (“Production is paused in mint. Someone needs to resume it.”), production_failed (“Production failed in mint. Someone needs to check it.”), planning_failed (“Planning the storyboard failed in mint. Someone needs to check it.”), automation_failed (“The automatic storyboard could not be completed. Someone needs to continue in mint.”), insufficient_credits (“The company does not have enough credits. Someone needs to add credits and continue in mint.”), automation_disabled (“Automatic production is currently switched off. Someone needs to continue in mint.”).
  - `code` (enum, required):  Values: `production_paused`, `production_failed`, `planning_failed`, `automation_failed`, `insufficient_credits`, `automation_disabled`.
  - `message` (string, required): Short English text (may change).
- `source` (enum, required): api: ordered through the API; app: reserved for projects created in mint (not returned in v1). Values: `api`, `app`.
- `automation` (nullable enum, required): none: mint only creates the film with its briefing; people continue in mint. storyboard (default): mint plans and produces the storyboard automatically and stops at storyboard_ready for review. film: mint also renders the film without stopping at the storyboard (status film_ready). The film is always approved by a person in mint, never by the API. Values: `none`, `storyboard`, `film`.
- `video_key` (nullable string, required): Your key of the video, as sent.
- `version` (nullable string, required): Version of the video, canonical (1.0.0 is returned as 1.0).
- `previous_version_id` (nullable string, required): Id of the film with the next lower version of the same video_key, or null.
- `is_latest_approved_version` (boolean, required): true only if this film is approved and no higher, approved and not cancelled version of the same video_key exists.
- `language` (nullable enum, required): Language of the film. Values: `de`, `en`, `fr`, `es`, `it`, `pt`, `nl`, `pl`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `sv`, `da`, `no`, `fi`, `tr`, `id`, `vi`, `el`, `uk`, `ru`, `bg`.
- `template` (nullable string, required): Key of the template used when the film was created.
- `settings` (object, required): Effective settings of the film in mint. Values that are not set (or that mint cannot express in the API) are null.
  - `format` (nullable enum, required): Aspect ratio. Values: `16x9`, `9x16`, `1x1`.
  - `style_id` (nullable string, required): Id of the style (see GET /styles).
  - `style_revision` (nullable integer, required): Revision of the style the film uses.
  - `brand_id` (nullable string, required): Effective brand (see GET /brands); null = no brand.
  - `voice_id` (nullable string, required): Voice of the narration (may also be a voice from the mint voice library); null = none set yet.
  - `voice_name` (nullable string, required): Name of the voice.
  - `narration_mode` (nullable enum, required): verbatim (default): narration_text is spoken word for word. smooth: mint polishes the language of narration_text and keeps its content. free: narration_text is the briefing; mint writes the narration freely (use target_duration_s for the length). Values: `verbatim`, `smooth`, `free`.
  - `tempo` (nullable enum, required): Pace of the film. Values: `presenting`, `lively`, `kinetic`.
  - `freedom` (nullable enum, required): Creative freedom in percent. Values: `0`, `25`, `40`, `65`, `100`.
  - `video_share` (nullable enum, required): Share of moving video clips in percent. Values: `0`, `25`, `50`, `75`, `100`.
  - `target_duration_s` (nullable integer, required): Target duration in seconds (in steps of 6 seconds).
- `category` (nullable object, required): Category of the film in mint (see GET /categories), or null.
  - `object` (string):
  - `id` (string, required): Id of the category.
  - `name` (string, required):
  - `external_key` (nullable string, required): Key of the connected system, if set.
  - `parent` (nullable object, required): Top-level category of a subcategory; null for a top-level category.
    - `id` (string, required):
    - `name` (string, required):
    - `external_key` (nullable string, required):
- `requested_by` (nullable object, required): The mint user from user_email of the request (a Person with kind user). This user is responsible for the film in mint and is notified when the storyboard is ready. Personal data.
  - `kind` (enum, required): Always user. Values: `user`.
  - `email` (string, required): E-mail address (lower case).
  - `name` (nullable string, required): Name of the user at the time the film was created.
- `metadata` (object, required): Your metadata, as sent. mint never uses it for the film. Key order is kept in POST /films (first response), GET /films and GET /films/{id}; a replayed response may order keys differently.
- `approval` (nullable object, required): The active approval of the film (only the approved original version is the film), or null.
  - `revision` (integer, required): Approved revision of the film.
  - `approved_at` (string (date-time), required): Time of the approval (UTC).
  - `sha256` (nullable string, required): SHA-256 of the approved file (hex).
  - `bytes` (nullable integer, required): Size of the approved file in bytes.
  - `duration_s` (nullable number, required): Duration in seconds.
  - `resolution` (nullable string, required): Resolution, e.g. 1920x1080.
  - `mime` (nullable string, required): Media type of the file, e.g. video/mp4.
  - `has_subtitles` (boolean, required): true if subtitles were frozen with this approval (subtitles_url).
  - `approved_by` (nullable object, required): Who approved the film in mint (kind user, name and e-mail; email is null for approvals before 9 November 2026). Personal data.
    - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
    - `name` (nullable string, required): Name of the user, or the name of the API access.
    - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
- `cancelled_at` (nullable string (date-time), required): Time of the cancellation (UTC), or null.
- `created_at` (string (date-time), required): Creation time (UTC).
- `updated_at` (string (date-time), required): Last change (UTC).
- `app_url` (nullable string, required): Link to the film in mint (for people with access), or null.
- `file_url` (nullable string, required): Path of the approved file (GET /films/{id}/file, relative to the host of the API), or null without an active approval.
- `subtitles_url` (nullable string, required): Path of the subtitles of the approval (GET /films/{id}/subtitles.srt), or null if the approval has none.
- `revisions` (array of objects): Rendered revisions of the film, newest last (only in GET /films/{id}, without file links).
  - `revision` (integer, required): Number of the rendered revision.
  - `status` (enum, required): rendering, ready or failed. Values: `rendering`, `ready`, `failed`.
  - `created_at` (nullable string (date-time), required): Start of the render (UTC).
  - `finished_at` (nullable string (date-time), required): End of the render (UTC), null while rendering.
  - `duration_s` (nullable number, required): Duration in seconds.
  - `resolution` (nullable string, required): Resolution, e.g. 1920x1080.

## Example

```json
{
  "object": "film",
  "id": "k7m2xq9v4t8n1b5r3c6d0wza",
  "title": "Lesson 3: Market segmentation",
  "status": "approved",
  "stage": "approved",
  "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": {
    "revision": 2,
    "approved_at": "2026-11-11T14:30:00Z",
    "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
    "bytes": 48213377,
    "duration_s": 184.6,
    "resolution": "1920x1080",
    "mime": "video/mp4",
    "has_subtitles": true,
    "approved_by": {
      "kind": "user",
      "name": "Anna Schmidt",
      "email": "anna.schmidt@example.edu"
    }
  },
  "cancelled_at": null,
  "created_at": "2026-11-10T08:00:00Z",
  "updated_at": "2026-11-11T14:30:00Z",
  "app_url": "https://app.cream-ai.de/editorial/k7m2xq9v4t8n1b5r3c6d0wza",
  "file_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/file",
  "subtitles_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/subtitles.srt",
  "revisions": [
    {
      "revision": 1,
      "status": "ready",
      "created_at": "2026-11-10T08:21:37Z",
      "finished_at": "2026-11-10T08:39:10Z",
      "duration_s": 181.2,
      "resolution": "1920x1080"
    },
    {
      "revision": 2,
      "status": "ready",
      "created_at": "2026-11-11T13:50:00Z",
      "finished_at": "2026-11-11T14:05:41Z",
      "duration_s": 184.6,
      "resolution": "1920x1080"
    }
  ]
}
```