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.

StatusMeansWhat to do
queuedAccepted, not startedWait
in_progressRunning — most videoPoll or take the webhook
completedAssets are attachedRead assets[0].url
failederror says whyRead error; the provider payload is kept

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.