# Film versions

Your system usually has its own id for a video, for example a lesson in a course. Send it as `video_key`, together
with a `version`. mint then treats `video_key` + `version` as the identity of the film within your company.

- Every film is ordered on behalf of a person: `user_email` must belong to an active member of your company. This person
  is the owner of the film in mint and gets the e-mail "storyboard ready", together with the admins of your company.
- `automation` is `storyboard` (default), `film` or `none`. With automation, mint needs a fixed style (from the template
  or `settings.style_id`) and enough credits for the estimated film (`402 insufficient_credits` otherwise). The operator of a
  mint server can switch the automation off; films are then created without it and carry `notice.code`
  `automation_disabled`.
- Credits are always taken from the credits of your company, never from a team budget. Each booking of an API film is marked
  "API" with the name of the access in the usage list of your company.
- `video_key` + `version` identify a film version. The same order again returns the existing film (`200`, nothing is
  booked); a different order for an existing version returns `409 version_conflict`.
- Film status: `briefing`, `in_production`, `storyboard_ready`, `film_ready`, `approved` or `cancelled`. Only the approved
  original version is the film; format and language versions are not part of v1.

### Versions in practice

| You send | mint does |
|---|---|
| `MKT101-lesson-03` `1.0`, first time | creates the film (`201`) |
| the same order again | returns the existing film (`200`), books nothing |
| `1.0` again, but with a changed text | `409 version_conflict` with `details.film_id` |
| `1.1` with a changed text | creates a new film that takes over style, brand, voice and category of `1.0` |

Versions are `major.minor` or `major.minor.patch` without leading zeros. Use `GET /films?video_key=…` to list all
versions of a video; `is_latest_approved_version` marks the newest approved one.

```json Order version 1.1
{
  "title": "Lesson 3: Market segmentation",
  "narration_text": "Not every customer wants the same thing. …",
  "user_email": "anna.schmidt@example.edu",
  "video_key": "MKT101-lesson-03",
  "version": "1.1"
}
```

```sh All versions of a video
curl "https://api.cream-ai.de/api/v1/films?video_key=MKT101-lesson-03" \
  -H "Authorization: Bearer $MINT_API_KEY"
```