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

# Generation lifecycle

> Model requests, outputs, failures, and application context with the Keeps SDK.

A generation is the request context around zero, one, or many output assets.
The useful product unit is each output asset, not only the provider request.

## Start before the provider call

Call `generation()` immediately before the existing provider invocation.

* `model` is the provider's model identifier.
* `provider` is optional.
* `input` is the exact JSON-compatible request sent to the provider.
* `properties` are facts your application already knows, such as feature,
  surface, campaign, or template.
* `userId`/`user_id`, `sessionId`/`session_id`, and source assets are optional
  exact join fields.

Do not copy model settings from `input` into `properties`.

## Complete with every output

Call `complete()` once after the provider succeeds. Include every output, even
when the user initially sees only one of them.

Each output requires:

* one stable external ID from your application;
* its media type: image, video, or audio.

A fetchable URL and media metadata are optional. Never use a URL as identity.

## Product-relevant failures

Use `fail()` when a terminal state is meaningful product context, such as a
safety or policy block. Generic provider failures do not have to be captured.

The SDK assigns event timestamps automatically. `keeps.timestamp()` is a
separate helper for marking an annotation value as a timestamp.