Concepts
Four nouns. Everything else is a verb applied to them.
Model
A generator with an id, a modality and its own input schema. Ids are the provider’s own — black-forest-labs/flux-1-schnell, google/veo-3.1 — so they are recognisable and never invented by us.
Every model declares what it accepts. That schema is the authority: there is no shared parameter list that models opt into, which is why params is the model’s own object rather than a normalised one.
Task
One run. Created the moment you call run, before the provider is reached, so a run that fails still has a record saying why.
Asset
What came out: a URL, a mime type and a size. URLs are short handles that re-sign on each fetch, so they do not expire in your database the way a presigned URL does.
Cost
Every task carries one. estimated: true means the provider bills by tokens and the real figure is not known until it reports usage — it is an honest unknown rather than a confident wrong number.