Introduction

The mint API lets your own systems (for example a learning platform) read the catalogs, briefing templates and categories of your company in mint, create categories and order films: POST /films creates a film from a briefing (title, narration text, template or settings); mint can then plan it and produce it automatically up to the storyboard or the finished film. Read your films with GET /films and GET /films/{id} and cancel them with POST /films/{id}/cancel until the storyboard is ready. Follow changes in the event feed GET /events and download approved films with GET /films/{id}/file (and their subtitles). It is a server-to-server API: browsers on other sites cannot call it (no CORS).

Base URL

https://api.cream-ai.de/api/v1. All paths in this document are relative to it. Requests and responses use JSON (UTF-8) unless an endpoint says otherwise, for example file downloads and uploads. All times are UTC in ISO 8601.

How a film flows through the API

1. Read your catalogs once: templates, styles, brands, voices and categories.
2. Order a film with POST /films. mint plans and produces it up to the storyboard (or the film).
3. Follow its state with the event feed or GET /films/{id}/progress.
4. Optionally review it: a storyboard preview, feedback on scenes, comments on the finished film.
5. A person approves the film in mint. Then download it with GET /films/{id}/file.

From zero to a downloaded film in six steps. You need an API key with the scopes catalog:read, films:write, events:read and files:read.

1. Create an API key

A company admin creates an API access in mint under Settings → API access, chooses the scopes and copies the key. The key is shown only once. Keep it on your server, for example in an environment variable:

export MINT_API_KEY="mint_sk_live_…"

2. Check the key

GET /me shows the access, its company, scopes and limits. A 401 means the key is wrong, revoked or expired.

3. Pick a template

GET /templates lists the briefing templates of your company. A template fixes the style, brand, voice and further settings, so the order itself stays short. Use its key as template.

4. Order the film

POST /films with a title, the narration text, the e-mail address of the responsible mint user and your own video_key + version. With automation: "storyboard" (the default) mint plans and produces the storyboard and then waits for review. Sending the same order again returns the same film, so retries are safe.

5. Follow the progress

Poll the event feed, for example every few minutes, or read GET /films/{id}/progress while a person is watching. film.storyboard_ready tells you that the storyboard can be reviewed in mint; film.approved that the film is final.

6. Download the approved film

GET /films/{id}/file returns the MP4. Its ETag is the SHA-256 of the file; compare it after the download.

Company admins create an API access in mint under Settings → API access. Each access has its own scopes and keys. A key is shown only once, right after it was created. Send it in the Authorization header:

curl -H "Authorization: Bearer mint_sk_live_…" https://api.cream-ai.de/api/v1/me

Keys in query strings are never accepted. GET /me shows the access, its company, scopes, key and limits. Revoking a key or changing scopes in mint takes effect immediately.

The mint API must be enabled for your company by mint. Until then, or after it was disabled, every request with a key of this company returns 403 api_not_enabled; your accesses and keys are kept and work again once the API is enabled.

Keep keys secret

• Use the key only from your server. The API does not allow calls from browsers on other sites (no CORS).
• Do not put keys into source code, URLs, tickets or logs. Store them in a secret store or an environment variable.
• Each access can have up to two valid keys at the same time, so you can rotate a key without downtime: create the new key, deploy it, then revoke the old one.
• An access can be limited to IP addresses and can expire. GET /me shows expires_at.

Every API access has its own scopes. A request with a key that lacks a scope returns 403 forbidden_scope; details.required_scopes names what is missing. Writing scopes include reading the same area.

GET /me and GET /openapi.json need no scope. More scopes follow with later versions.

Endpoints by scope

mint uses HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a problem on the mint side.

All errors share one format:

{ "error": { "code": "forbidden_scope", "message": "…", "request_id": "req_…", "field": "…", "details": {} } }

code is stable and machine readable, message is for humans and may change, field names the affected input. Every response carries an X-Request-Id header; please quote it when you contact support.

Handling errors

• Branch on error.code, never on message.
• 429 and 503 are temporary: wait for Retry-After seconds and retry the same request with the same Idempotency-Key.
• 409 codes with Retry-After (for example film_busy, idempotency_in_progress) are temporary as well.
• New codes may be added within v1. Treat an unknown 4xx code like invalid_request and an unknown 5xx code like internal.

Error codes

Networks fail. With an Idempotency-Key you can safely send a writing request again: mint runs it at most once and returns the stored response for every repeat.

Writing POST requests require an Idempotency-Key header (1–128 visible ASCII characters, for example a UUID); PATCH accepts it optionally. POST /films accepts it optionally when the body has a video_key (the version identity then protects against duplicates); without video_key it is required (400 idempotency_key_required). POST /films/{id}/cancel accepts it optionally. Repeating a request with the same key and the same body returns the stored response with Idempotent-Replayed: true and changes nothing. This also applies to error responses (400, 404, 409): their body is replayed unchanged, so error.request_id names the original request, while X-Request-Id names the current one. Temporary rejections are not stored (409 feedback_busy, 409 film_busy, 409 preview_in_progress, 409 storyboard_not_ready, 402 insufficient_credits, 409 feedback_queue_full): a retry with the same key runs again once the reason is gone. The same key with a different request returns 422 idempotency_mismatch; while the first request is still running you get 409 idempotency_in_progress with Retry-After. Keys are kept per API access for 24 hours by default; the operator of a mint server can set 1–72 hours. GET /me shows the current value in idempotency_key_ttl_hours.

Good practice

• Create a new random key (for example a UUID v4) for every new action, and reuse it only for retries of that action.
• Store the key together with your own job, so a retry after a crash uses the same key.
• For films, prefer video_key + version (see Film versions): they protect against duplicates for as long as the film exists, not only for 24 hours.

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

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.

Lists return { "object": "list", "data": [], "has_more": false, "next_cursor": null }. Pass next_cursor as cursor to get the next page; limit is 1–100 (default 50). Cursors are opaque and only valid for the same query and filters.

The list object

The event feed is the exception: it pages with after and next_after instead of a cursor, see Event feed.

mint v1 has no webhooks. Instead, every company has an ordered event feed: you ask for everything after the last event you processed. This works behind firewalls, needs no public endpoint on your side and never loses an event while your system is down.

A person approves a film in mint; only then can it be downloaded. The key needs films:read, events:read and files:read. Downloads and the feed are free of credits.

1. GET /events?limit=1: note latest_seq as H.
2. GET /films?status=approved (all pages): download each film from file_url and compare the SHA-256 of the bytes with the ETag.
3. From then on, for example once a day: GET /events?after=H&types=film.approved,film.approval_revoked,film.deleted, process the events, store next_after as the new H, repeat while has_more.
4. 410 cursor_expired or 400 invalid_cursor: start again with step 1.

A film can be downloaded as long as its approval is active: after a revocation the download returns 404 not_approved; after a new approval only the new revision is available. Films that change between step 1 and 2 come twice; that is harmless because the SHA-256 identifies the file.

Event types

• film.created
• film.status_changed
• film.storyboard_ready
• film.approved
• film.approval_revoked
• film.cancelled
• film.deleted
• film.progress
• feedback.updated
• storyboard.preview_ready
• operation.completed

New types may be added within v1; ignore types you do not know. Events are kept for 180 days.

Rules for a robust consumer

• Store next_after only after the page was processed. If you crash in between, you read the page again.
• Events can come twice (at least once delivery). Use the event id to skip duplicates.
• data is a snapshot at the time of the event; film (with films:read) is the current state.
• Poll every few minutes. There is no need to poll faster than once a minute.

Approved films are downloaded with GET /films/{id}/file, their subtitles with GET /films/{id}/subtitles.srt. Storyboard previews work the same way with GET /films/{id}/storyboard-preview/file. Downloads are free of credits.

ETag = SHA-256

Every file comes with a strong ETag: the SHA-256 of the file in quotes. For films it equals approval.sha256 of the film. Compute the SHA-256 of the bytes you received and compare. If an event is older than the current approval, the ETag counts.

Resume a download

Send Range: bytes=<from>- together with If-Range: <ETag>. If the file is unchanged, mint answers 206 with the rest; if a new approval exists in the meantime, 200 with the whole new file. One range per request is supported.

Skip unchanged files

Send If-None-Match: <ETag>. mint answers 304 without a body if you already have the current file. HEAD returns the headers only.

When a download is not possible

Long-running requests answer 202 Accepted with a Location header that points to /api/v1/operations/{id} and an Operation object. Poll it until status is succeeded or failed. Operation types are storyboard.preview and film.comments_apply; more may follow within v1.

The operation also reports its end in the event feed (operation.completed), so you can follow it there instead of polling. See Operations for the object and the endpoint.

Requests are limited per key and per company; GET /me shows the limits in rate_limits. Exceeding a limit returns 429 rate_limited with Retry-After (seconds). JSON request bodies may be at most 256 KB and nested at most 32 levels deep (otherwise 400 invalid_request with field body). An error before the body was read closes the connection (Connection: close). Catalog lists (styles, brands, voices) and the category list may show changes with a delay of up to 30 seconds.

Fixed limits

Within v1 there are only additions: new endpoints, new optional request fields, new response fields and new enum values. Ignore fields you do not know. Breaking changes come with a new version (/api/v2).

The version is part of the path (/api/v1). GET /me shows it in api_version. The complete contract is available as OpenAPI 3.1 at GET /openapi.json, for example to generate a client.