Quickstart

1. Create a workspace key

Open Keeps, sign in, and create or select a workspace. In Settings → API keys, mint a key and copy it when it is shown. Set that key only in the server environment that runs your generation code:

KEEPS_API_KEY=...

2. Install a server SDK

npm install @keeps-ai/node

pip install keeps-ai

Create one Keeps client at process scope. Do not create a new client for every request.

import { Keeps } from "@keeps-ai/node";

export const keeps = new Keeps({
  apiKey: process.env.KEEPS_API_KEY,
});

import os
from keeps import Keeps

keeps = Keeps(api_key=os.environ["KEEPS_API_KEY"])

3. Wrap one generation

Create the Keeps generation immediately before your existing provider call. Pass the exact provider request as input.

const input = {
  prompt,
  seed,
  width: 1024,
  height: 1024,
};

const generation = keeps.generation({
  model: "fal-ai/flux-2-pro",
  provider: "fal",
  input,
  userId,
  sessionId,
  properties: { feature: "canvas" },
});

const output = await mediaProvider.generate(input);

const result = generation.complete({
  assets: [
    {
      externalId: outputRow.id,
      mediaType: "image",
      url: output.signedUrl,
    },
  ],
});

input = {
    "prompt": prompt,
    "seed": seed,
    "width": 1024,
    "height": 1024,
}

generation = keeps.generation(
    model="fal-ai/flux-2-pro",
    provider="fal",
    input=input,
    user_id=user_id,
    session_id=session_id,
    properties={"feature": "canvas"},
)

output = media_provider.generate(input)

result = generation.complete(
    assets=[
        {
            "external_id": output_row.id,
            "media_type": "image",
            "url": output.signed_url,
        }
    ]
)

externalId/external_id should be the stable ID of the output in your own database. The URL is optional and is used to inspect the media; it is never the asset’s identity. If one request produces several outputs, include every output in the same complete call. Keeps creates an independently actionable asset for each one.

4. Track a meaningful action

Call track in the server handler where the action actually succeeds:

keeps.track("downloaded", {
  asset: result.assetIds[0],
  userId,
  sessionId,
});

keeps.track(
    "downloaded",
    asset=result.asset_ids[0],
    user_id=user_id,
    session_id=session_id,
)

Use product language your team already understands: approved, added_to_sequence, published, shared, or remixed are all valid examples.

5. Verify the result

Open Assets in the workspace. The first asset should show its generation context and the action you recorded. Settings shows instrumentation diagnostics if an output or action cannot be joined. At process shutdown or a serverless response boundary, perform one bounded flush. See Serverless and shutdown.

Keeps capture runs in the background and fails open. A Keeps delivery problem does not change the result of your media-generation request.

Get started

Instrument your product

Use your data

1. Create a workspace key

2. Install a server SDK

3. Wrap one generation

4. Track a meaningful action

5. Verify the result

​1. Create a workspace key

​2. Install a server SDK

​3. Wrap one generation

​4. Track a meaningful action

​5. Verify the result

1. Create a workspace key

2. Install a server SDK

3. Wrap one generation

4. Track a meaningful action

5. Verify the result