Skip to main content
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.