> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mint.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Videos

> Generate playable videos from prompts, images, and existing media references.

Create a video with `POST /v1/videos:generate`, poll its operation, then download the finished clip.

## Generate a video

```bash theme={null}
curl https://api.mint.gg/v1/videos:generate \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: courtyard-video-001" \
  -d '{
    "prompt": "A slow camera move through a sunlit courtyard, leaves moving gently",
    "generationPreset": "standard",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "generateAudio": true
  }'
```

The response contains an operation and, once generation starts, `operation.resource` with type `video` and the asset ID. Poll `GET /v1/operations/{operationId}` until it succeeds or fails. API videos save to your account library without creating a chat or personal Project.

Video starts final generation directly and does not accept `generationMode`. There is no Preview approval step on this endpoint.

| Field              | Behavior                                                                                                                                                                                                                                                                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`           | Required, up to 8,000 characters.                                                                                                                                                                                                                                                                                     |
| `name`             | Optional title, up to 120 characters.                                                                                                                                                                                                                                                                                 |
| `generationPreset` | `fast`, `standard` (default), or `production`.                                                                                                                                                                                                                                                                        |
| `videoMode`        | `text_to_video` (default), `image_to_video`, `first_last_frame`, or `reference_to_video`.                                                                                                                                                                                                                             |
| `durationSeconds`  | Whole seconds: Fast and Standard support 5–15; Production supports 4–15. Defaults to 8, or to the duration of a sole video reference rounded to whole seconds. Unsupported durations are rejected. Specify a duration when using multiple video references.                                                           |
| `aspectRatio`      | `16:9` (default) or `9:16`. Image and first/last-frame modes in every preset follow the start image's framing: its landscape/portrait orientation must match this setting. Square or opposite-orientation starts are rejected before generation. Reframe the start image before submitting to change its orientation. |
| `generateAudio`    | Defaults to `true`. Use Production for `false`; Fast and Standard always generate audio.                                                                                                                                                                                                                              |
| `references`       | Owned Mint reference asset IDs with explicit roles. Each ID can appear once.                                                                                                                                                                                                                                          |

## Use references

Upload an image with [reference-image upload](/developers/images), then use the returned reference asset ID. Existing video and audio references uploaded in Mint can also guide a new clip. This endpoint accepts reference IDs, not arbitrary media URLs or file bytes.

```json theme={null}
{
  "prompt": "The scene comes alive with a gentle camera push forward",
  "videoMode": "image_to_video",
  "references": [
    { "referenceAssetId": "YOUR_REFERENCE_IMAGE_ID", "role": "start_frame" }
  ]
}
```

* `text_to_video` takes no references.
* `image_to_video` requires exactly one image with role `start_frame`.
* `first_last_frame` requires one `start_frame` image and one `end_frame` image.
* `reference_to_video` uses only role `reference`. Fast and Standard accept up to 9 images and 3 videos, 12 files total, with at most 15 seconds of reference video. Production accepts up to 30 images, 10 videos, and 10 audio files, 50 files total, with up to 30.2 seconds each of combined video and audio. Audio references require Production and at least one image or video reference.

References must belong to your account and remain available. Image references must pass Mint's safety checks. Reference guidance creates a new clip; it does not edit an encoded video in place or guarantee exact timing or motion.

## Retrieve the video and files

Call `GET /v1/videos/{videoId}` for status, the durable `videoUrl`, poster when available, duration, aspect ratio, and file metadata. For new completed videos, `width`, `height`, and duration are read from the delivered file. `aspectRatio` describes the requested landscape/portrait setting; image-driven framing and provider resolution rounding can produce a different exact raster ratio. List videos with `GET /v1/assets?type=video`.

Use the [Assets](/developers/assets) artifact routes with `assetType=video`. The finished clip has artifact ID `video_file`; its manifest provides a durable download URL, `loaderHint: "video"`, and a suggested path under `public/videos/`. Downloads require ownership, successful generation, and download permission.

## Estimate Credits and retry requests

Use `POST /v1/pricing:estimate` with `operation: "video_generation"`, `generationPreset`, `videoMode`, and `durationSeconds`. For reference-guided work, also supply `referenceImageCount` and `referenceVideoDurationSeconds` (the combined video-reference duration). Estimates are advisory; generation validates the actual references and reserves Credits before starting.

If admission returns `402 billing-required`, keep the operation ID, resolve billing, and repeat the original generation request with the same `Idempotency-Key`. A started request replay returns the existing operation. A new request key starts new work and can spend Credits again.