Core concepts

Provider accounts

Your provider accounts, what we do with them, and the catalog they draw from.

A provider account is one credential of yours at one model provider, under a label you choose. Models resolve to an account, so the account is where cost, health and rotation live.

Connect

seams providers connect production --provider anthropic --key sk-ant-…

# provider   anthropic
# label      production
# last four  8c21
# status     active

import { Seams } from "@ourseams/sdk"

const seams = new Seams({ apiKey: process.env.SEAMS_API_KEY! })
const account = await seams.providers.connect("production", {
  provider: "anthropic",
  apiKey: process.env.ANTHROPIC_API_KEY!,
})

import os
from seams import Seams, models

seams = Seams(api_key=os.environ["SEAMS_API_KEY"])
account = seams.providers.connect(
    "production",
    provider="anthropic",
    api_key=os.environ["ANTHROPIC_API_KEY"],
)

The label is the path, so connecting twice under the same label replaces the credential rather than creating a second account. That is what makes the call safe to run from a deploy script.

Health, rotation, and negotiated rates

probe sends one cheap call and records the result. Rotating replaces the plaintext behind the same label. Override list prices when you have negotiated rates, margin arithmetic uses your number.

seams providers probe production
seams providers rotate production --key sk-…
seams providers price production gpt-4o-mini --input 0.10 --output 0.40
seams providers show production
seams providers models production

await seams.providers.probe("production")
await seams.providers.rotate("production", { apiKey: process.env.OPENAI_API_KEY! })
await seams.providers.price("production", {
  model: "gpt-4o-mini",
  override: { input: "100000", output: "400000", cachedInput: null },
})
await seams.providers.show("production")
await seams.providers.models("production")

seams.providers.probe("production")
seams.providers.rotate("production", api_key=os.environ["OPENAI_API_KEY"])
seams.providers.price(
    "production",
    model="gpt-4o-mini",
    override=models.ProviderPrice(input="100000", output="400000", cached_input=None),
)
seams.providers.show("production")
seams.providers.models("production")

This is the cost side, not the sell side. What your end users pay is set on the bundle; the two are deliberately separate numbers so margin is a subtraction rather than a guess.

The catalog

The catalog is the curated list we know how to price and route. It is what models.add --source draws from.

seams catalog providers
seams catalog models
seams catalog show anthropic/claude-sonnet-4

await seams.catalog.providers()
await seams.catalog.models()
await seams.catalog.show("anthropic/claude-sonnet-4")

seams.catalog.providers()
seams.catalog.models()
seams.catalog.show("anthropic/claude-sonnet-4")

Command	Answers
`catalog.models`	Every curated model, with price and context window
`catalog.show`	One model in full
`providers.models`	What this account has actually loaded

A model we cannot price is refused rather than estimated. usage_unmeasurable is a 500 that pages, on purpose: an incident is better than a guessed bill.